Programming with DOMAIN Advanced System Calls 



Order No. 008542 

Revision 00 

Software Release 9.0 



Apollo Computer Inc. 

330 Billerica Road 
Chelmsford, MA 01824 



Copyright © 1985 Apollo Computer Inc. 
All rights reserved. 
Printed in U.SA. 

First Printing: November, 1985 



This document was produced using the SCRIBE document preparation system. (SCRIBE is a 
registered trademark of Unilogic, Ltd.) 

APOLLO and DOMAIN are registered trademarks of Apollo Computer Inc. 

AEGIS, DGR, DOMAIN/Bridge, DOMAIN/Dialogue, DOMAIN/DC, DOMAIN/Laser-26, 
DOMAIN/PCI, DOMAIN/SNA, DOMAIN/VACCESS, D3M, DPSS, DSEE, GMR, and GPR are 
trademarks of Apollo Computer Inc. 

Apollo Computer Inc. reserves the right to make changes in specifications and other information 
contained in this publication without prior notice, and the reader should in all cases consult 
Apollo Computer Inc. to determine whether any such changes have been made. 

THE TERMS AND CONDITIONS GOVERNING THE SALE OF APOLLO COMPUTER INC. HARDWARE 
PRODUCTS AND THE LICENSING OF APOLLO COMPUTER INC. SOFTWARE CONSIST SOLELY OF THOSE 
SET FORTH IN THE WRITTEN CONTRACTS BETWEEN APOLLO COMPUTER INC. AND ITS CUSTOMERS. NO 
REPRESENTATION OR OTHER AFFIRMATION OF FACT CONTAINED IN THIS PUBLICATION, INCLUDING 
BUT NOT LIMITED TO STATEMENTS REGARDING CAPACITY, RESPONSE-TIME PERFORMANCE, 
SUITABILITY FOR USE OR PERFORMANCE OF PRODUCTS DESCRIBED HEREIN SHALL BE DEEMED TO BE A 
WARRANTY BY APOLLO COMPUTER INC. FOR ANY PURPOSE, OR GIVE RISE TO ANY LIABILITY BY 
APOLLO COMPUTER INC. WHATSOEVER. 

IN NO EVENT SHALL APOLLO COMPUTER INC. BE LIABLE FOR ANY INCIDENTAL, INDIRECT, SPECIAL OR 
CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING BUT NOT LIMITED TO LOST PROFITS) ARISING 
OUT OF OR RELATING TO THIS PUBLICATION OR THE INFORMATION CONTAINED IN IT, EVEN IF APOLLO 
COMPUTER INC. HAS BEEN ADVISED, KNEW OR SHOULD HAVE KNOWN OF THE POSSIBILITY OF SUCH 
DAMAGES. 

THE SOFTWARE PROGRAMS DESCRIBED IN THIS DOCUMENT ARE CONFIDENTIAL INFORMATION AND 
PROPRIETARY PRODUCTS OF APOLLO COMPUTER INC. OR ITS LICENSORS. 



Preface 



This manual describes newly released DOMAIN system calls. These calls are in addition to those 
released in the DOMAIN System Call Reference. This manual is intended to provide adequate 
documentation and syntax information for many existing system calls. This reference material is 
intended for programmers who have experience programming with DOMAIN system routines and 
insert files. 

This manual is divided into two parts. Part I contains a general overview of a separate operating 
subsystem (e.g., the Command Line Handler, File and Tree Utility). Most chapters conclude with 
a sample program in Pascal demonstrating the calls. 

Part II consists of reference information similar to the DOMAIN System Call Reference. Each 
subsystem has its own section, which contains the data types the subsystem uses, the syntax of its 
programming calls, and the error messages it generates. 

Some calls described in this book belong to released subsystems (PM, PROC2, and RWS) that are 
described in the DOMAIN System Call Reference manual. To make it easy for you to 
incorporate this information, we repeated the entire sections, marking the new material with 
revision bars. This way, you can replace the entire section in your copy of the manual. 

For easy organization, the sections in Part II are in alphabetical order by subsystem name. We 
numbered the pages of Part II by subsystem. For example, the third page in the CL section is 
page CL-3. 

You should use this manual with the programming handbooks listed under Related Documents . 
These programming handbooks give detailed instructions about using these programming calls. 

Audience 

This manual is intended for advanced programmers who are writing application programs using 
DOMAIN system calls. Readers of this manual should be familiar with general DOMAIN system 
calls as described in Programming with General System Calls. They should also have experience 
with FORTRAN, Pascal, or C and the operating system as described in the DOMAIN System 
User's Guide. This manual is not intended as a tutorial document, but as a reference for 
programmers who need to use operating system calls. 

Related Documents 

The Programming With General System Calls handbook (005506), documents how to write 
programs that use standard DOMAIN system calls including the ACLM, CAL, EC2, ERROR, 
MTS, NAME, PAD, PBUFS, PFM, PGM, PM, PROCl, PROC2, RWS, SIO, STREAM, TIME, 
TONE, TPAD, and VFMT calls. 

The Programming With System Calls for Interprocess Communication handbook (005696), 
documents how to write programs that use the DOMAIN interprocess facilities including the 
MBX, MS, IPC, MUTEX, and EC2 calls. 

The Programming With DOMAIN 2D Graphics Metafile Resource handbook (005097), 
documents how to write programs that use the DOMAIN 2D Graphics Metafile Resource. 

The Programming With DOMAIN Graphic Primitives handbook (005808), documents how to 
write graphics programs that use the DOMAIN Graphics Primitive Resource. 
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Documentation Conventions 

Unless otherwise noted in the text, this manual uses the following symbolic conventions. 



UPPERCASE 



lowercase 



Uppercase vords or characters in formats and command 
descriptions represent keywords that you must use 
literally. 

Lowercase words or characters in formats and command 
descriptions represent values that you must supply. 

Square brackets enclose optional items. 

Braces enclose a list from which you must choose an 
item. 



CTRL/Z 



A vertical bar separates items in a list of choices 

Angle brackets enclose the name of a key on the 
keyboard . 

The notation CTRL/ followed by the name of a key 
indicates a control character sequence . Hold down 
<CTRL> while you type the character. 

Horizontal ellipsis points indicate that you can 
repeat the preceding item one or more times . 

Vertical ellipsis points mean that we have omitted 
irrelevant parts of a figure or example . 



Problems, Questions, and Suggestions 

We appreciate comments from the people who use our system. In order to make it easy for you 
to communicate with us, we provide the User Change Request (UCR) system for software-related 
comments, and the Reader's Response form for documentation comments. By using these formal 
channels, you make it easy for us to respond to your comments. 

You can get more information about how to submit a UCR by consulting the DOMAIN System 
Command Reference manual. Refer to the CRUCR (Create User Change Request) Shell 
command description. You can view the same description on-line by typing: 

$ HELP CRUCR <RETURN> 

For documentation comments, a Reader's Response form is located at the back of each manual. 
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Chapter 1 
Parsing the Command Line 



The Common Command Line Handler (CL) is a set of DOMAIN system routines that provides an 
easy and consistent way to read tokens from the command line. CL can perform the following: 

• Expand wildcards to existing pathnames 

• Handle derived names 

• Handle names-file input when the user specifies the "*" operator 

• Parse command lines from the keyboard or specified files. 

Before reading this chapter, you should be familiar with the user-visible features of CL. These 
features are described in detail in the DOMAIN System Command Reference manual and the 
DOMAIN System User's Guide. 

CL calls are often used in conjunction with File & Tree Utility (FU) calls. For more examples of 
the CL, you might want to refer to Chapter 2, Using the File and Tree Utility (FU). 

1.1. System Calls, Insert Files, and Data Types 

To use the CL manager, use the system calls with the CL prefix. This chapter describes how 
most of these calls work. For details on CL call syntax, data types, and error messages, see Part 
II of this manual. 

When using CL system calls in your program, you must specify the appropriate insert file for the 
language your are using. The CL insert files are 

/SYS/INS/CL.INS.C for C. 

/SYS/INS/CL.INS.FTN for FORTRAN. 

/SYS/INS/CL.INS.PAS for Pascal. 



1.2. Overview of the CL Manager 

Before we describe how the CL manager works, we need to define a few terms that it uses. 

A token is a text string that CL reads from the command line and parses according to the Shell 
parsing rules. 

A names-file is a text file containing pathnames. CL reads the contents of a names-file as if it 
appeared on the command line. Tokens in a names-file can be delimited by spaces, or the 
NEWLINE character. 

A flag is a token beginning with the hyphen, "-". Flags allow you to specify special actions so 
that the user can make optional choices on the command line. 
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While we refer to hyphenated words as flags, the DOMAIN System Command Reference manual 
refers to them as options. Also, some CL system calls refer to flags as keywords. 

An argument is any token that is not a flag. 

A wildcard- name is an argument that represents one or more existing pathnames. CL accepts 
wildcard characters as part of pathname arguments, and expands them to pathnames. These 
wildcard characters are listed in the DOMAIN System Command Reference manual. 

A derived name is a name that is derived from another name. For example, Shell commands 
handle derived names with the = wildcard. The Shell command line $ cpf name =.derived 
copies the file "name" to "name.derived." For details on derived names, see the DOMAIN 
System Command Reference manual. 

When the CL manager reads the command line, it places each token from the command line and 
any names-files into an individual token record. The token records form a linked list or token 
list, which resides in scratch space. Initially, the token pointer points to the head of the list. 
When using CL system calls to read tokens from the list, the token pointer keeps track of the 
most recent token read. 

Figure 1-1 shows the structure of a token list. 

Command line: command argument argument -flag *names-f lie 
Token List: 



Command 


Argument 


Argument 


-Flag 


Name from 
names-file 


Name from 
names-file 



Token Pointer 

Figure 1-1. Structure of a Command Line Token List 

Once you initialize the CL, you make other CL calls to read the flags and names from the 
command line. When making these calls, the CL refers to the token list, not the command line or 
names-files. 

NOTE: CL does not expand wildcards at initialization because it 
cannot determine which tokens represent names . Wildcard 
names and derived names are expanded later. 

When you make calls to get tokens, CL checks the token list for the token and marks it "used." 
Usually, once CL marks a token used, you cannot refer to it again. You can refer to a used token 
when handling derived names, or using any of the CL_$REREAD system calls. See Part II of 
this manual for details. 

When using the CL manager to parse your command line, you usually perform the following 
steps: 
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1. Use CL_$INIT to initialize the token list on which all subsequent CL calls operate. 

2. Use the appropriate GET_FLAG system call to read the token list for flags. 

3. If flags require arguments, get the associated arguments using the appropriate call: 
CL_$GET_NAME for pathnames, CL_$GET_NUM for numbers, or 
CL_$GET_ARGS for character strings. 

4. Check the token list for unclaimed flags with CL_$CHECK_UNCLAIMED. 

5. Establish a loop to read the token list for arguments using the appropriate system 
call: CL_$GET_NAME for pathnames, CL_$GET_NUM for numbers, or 
CL_$GET_ARGS for character strings. 

Figure 1-2 shows the basic model of for parsing the command line using CL calls. The next few 
sections describe these calls in detail. 



. < List include files. CONST. VAR sections > 

BEGIN < Main } 

cl_$init ( . . . ) ; 
-C Get specified flags. > 

IF cl_$get_flag (...) THEN . . .; 
< Get argument associated with flag . > 

IF cl_$get_flag (...) THEN BEGIN 



IF NOT cl_$get__arg ( . 
THEN error routine 



) 



< Convert to desired type, if necessary 
Handle arguments . > 



ELSE 

END; { if > 

< Check for any erroneous options that the user specified. > 

cl__$check_unclaimed; 

{ Establish a loop to read names or other arguments . > 

WHILE cl_$get_name (...) 

DO BEGIN 

< Do work here . > 

END; i do begin > 
END. < Program > 



Figure 1-2. Model for Parsing the Command Line 
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If an error occurs during a CL system call, CL prints an error message and performs a 
PGM_$EXIT and terminates your program. To prevent your program from terminating, you 
can set up a clean-up handler, as described in the Programming with General System Calls 
manual. 

The next sections describe how to use specific CL calls to initialize the CL manager and get 
tokens from the token list. 



1.3. Initializing the CL Manager 



When using the CL manager to handle the command line, you must first initialize it by calling 
CL_$INIT or CL_$SETUP. CL_$INIT initializes CL and parses the command line according 
to the Shell parsing rules. 

CL_$SETUP is like CL_$INIT in that it initializes CL manager, but it doesn't parse the 
command line. It allows you to supply a different source for the tokens, for example, from a file 
or interactively from the keyboard. You supply the additional CL parsing routines to perform the 
parsing. (For details, see Section 1.3.3.) 

When you initialize CL, you can specify certain options to control how CL reads the tokens from 
the command line. These options affect how CL interacts with the user. For example, you can 
tell CL not to expand any wildcards, or to verify each pathname it reads with the user. 

Table 1-1 lists the various CL calls that you can use to initialize CL and set up options. Sections 
1.3.1 and 1.3.2 describe the options you can specify when initializing the CL manager. Section 
1.3.3 is an example of initializing CL. 

Table 1-1. System Calls to Initialize the CL Manager 



System Call Name 



CL $INIT 



CL $SETUP 



CL SPARSE LINE 



CL SPARSE INPUT 



Description 



Initializes the command line handler, parsing the 
command line according to the Shell parsing rules. 

Initializes the command line handler, but does not 
load anything to parse. Use this call when the 
tokens come from a file or keyboard instead of 
the command line. You call one of the following 
CL parse calls to specify where the tokens are. 

Supplies the line for CL to parse. On 
subsequent calls, CL returns information from 
this line. It discards any previous arguments. 

Reads a line from the specified stream ID 
and hands it to CL_ SPARSE _ LINE. 
Returns TRUE if successful, FALSE if it 
encounters the end-of-file character. 



/' 
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Table 1-1. System Calls to Initialise the CL Manager, Cont. 



System Call Name 


Description 


CL_$PARSE_ARGS 

CL_$SET_WILD_OPTIONS 
CL_$SET_NAME_PREFDC 

CL_$SET_DERIVED_COUNT 

CL_$SET_OPTIONS 
CL _ $RESET _ OPTIONS 


Gets arguments from the keyboard. Use 
this after getting arguments with 
CL_$GET_ARG. This call disregards the 
first argument, because it assumes that it is the 
command name. 

Defines the wildcard options for the 
wildcard manager. 

Defines a character string prefix to add before 
each name specified on the command line. For 
example, you might want to add the prefix 
/sys/print, to names on a print queue command. 

Specifies the number of derived names allowed 
to follow each wildcard name. The default value 
is 1. 

Adds specified options to the CL option set defined 
in the CL _ $INIT or CL _ $SETUP call . 

Replaces the previously defined CL option set 
with the specified CL option set. 



1.3.1. Defining CL Options 

You can control how the CL reads the command line by specifying CL options with the 
CL_$INIT or CL_$SETUP call. You can let CL define a set of these options automatically, by 
specifying the default empty brackets, []. Or, you can specify alternative CL options, by listing 
the CL options in the brackets. 

Table 1-2 lists the default set of options, and their alternatives. Note that you can specify only 
one alternative per default option; the alternatives are mutually exclusive. 



Apollo Confidential 



1-5 



Parsing the Command Line 



Table 1-2. CL Options 



Default Option 


Mutually- Exclusive Alternatives 


CL_$WELDCARDS 

Causes CL_$GET_NAME to expand 

wildcards and return the expanded 

names. 


CL_$NO_WILDCARDS 
Causes CL_$GET_NAME to return 
wildcard-names verbatim; it does 
not expand them. 


CL _ $NO _MATCH_ WARNING 
Displays a warning message on 
error output when a wildcard 
does not match existing 
pathnames. 


CL__$NO_MATCH_OK 
Displays no warning or error 
message when a wildcard does not 
match existing pathnames. 

CL_$NO_MATCH_ERROR 
Displays an error message on 
error output, and terminates 
the program when a wildcard 
does not match an existing 
pathname. 


CL_$VERIFY_NONE 
CL_$GET_NAME does not 
verify any names with the 
by user. 


CL_$VERIFY_WILD 
CL_$GET_NAME verifies 
only names expanded 
wildcards with the user. 

CL_$VERIFY_ALL 
CL_$GET_NAME verifies all 
names with the user. 


CL_$STAR_NAMES 
Allows the user to specify 
names-files with the 
"*" operator. 


CL_$NO_STAR_NAMES 
Does not allow users to 
specify names-files. Treats the 
"*" just like any other character. 


CL __ $KEYWORD _ DELIM 
Prevents CL_$GET_ARG 
and CL_$GET_NAME 
from returning an "unused" 
flag as an argument. The 
calls return FALSE if they 
find a flag. 


CL _ $NO _ KEYWORD _ DELIM 
Causes no special treatment 
of unread flags by 
CL_$GET_ARG and 
CL_$GET_NAME. The procedures 
return the flags as if they 
were arguments. 


CL_$DASH_NOP 
CL treats the hyphen "-■ as a 
name. Normally, the hyphen is an 
identifier for the standard 
input stream. 


CL_$DASH_NAMES 
CL reads names from 
standard input when it finds 
a hyphen.* 
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Table 1-2. CL Options, Cont. 



Default Option 


Mutually- Exclusive Alternatives 


CL_$DASH_DFT_NOP 


CL_$NAME DFT STDIN 


Suppresses any special action when 


Causes CL to read names 


there are no arguments on the 


from standard input if no arguments 


command line. 


appear on the command line.* 


CL _ $NO _ COMMENTS 


CL_$COMMENTS 


Causes no special treatment 


Causes CL to ignore all 


of characters enclosed 


characters enclosed in brackets 


in brackets. 


when reading a names-file. Do not 




use this in commands that accept 




derived names because you must 




use brackets to specify the 




tag expressions you want to 




use in a derived name. 



* Made available to remain compatible with previous software releases. 
Obsolete for new software development. 

You can add options to the current CL option set at another time during your program by using 
the CL_$SET_ OPTIONS call. If you want to remove options from the current CL option set, 
you can specify an entirely new set of CL options with CL_$RESET_ OPTIONS. 
CL_$RESET__ OPTIONS replaces the previously defined CL option set with the option set 
specified in the call. 

Example 1-1 shows how a program changes the set of CL options. 



Initialize CL with specified CL options: 

This CL options set contains CL_$NO_ WILDCARDS, plus 

the default options: CL_$VERIFY_NONE, CL_$STAR_ NAMES, 

CL_$KEYWORD_DELIM, CL_$DASH_NOP, CL_$DASH_DFT_NOP, 

CL_$NO_COMMENTS. 

cl_$init ( [cl_$no_wildcards] . < Returns wildcards literally > 

program_name . { Name of program > 

sizeof (program_name)) ; < Length of program name > 

Add to the current set of CL options: 

This CL options set adds CL_$VERIFY_ALL to the option set listed above: 
cl_$set_options ([cl_$verify_all]) ; { Verify all names > 



Example 1-1. Redefining the CL Options Set 



Apollo Confidential 



1-7 



Parsing the Command Line 



Replace the current list of options with a new set: 

This CL options set contains the default set of options: CL__$ WILDCARDS, 
CL_$VERIFY_NONE, CL_$STAR_ NAMES, CL_$KEYWORD_DELIM, 
CL_$DASH_NOP, CL_$DASH_DFT_NOP, CL_$NO_ COMMENTS. 

cl_$reset_options ([]); 



Example 1-1. Redefining the CL Options Set, Cont. 



1.3.2. Defining Wildcard Options 

When you initialize the CL manager, it defines a default set of wildcard options that determine 
how the wildcard manager expands wildcards. You can change how the CL wildcard manager 
expands wildcards by specifying other wildcard options with the CL_ $SET _ WILD _ OPTIONS 
system call. 

Table 1-3 lists the wildcard options available. You can list any combination of wildcard options 
with CL_$SET_ WILD _ OPTIONS. Note that you must specify all the wildcard options you 
want in effect, including the default options. 

Table 1-3. Setting Wildcard Options 



Default? 


Wildcard Option 


Wildcards match: 


Yes 


CL_$WILD_FILES 


Names of files. 


Yes 


CL_$WILD_DIRS 


Names of directories. 


Yes 


CL_$WILD_LINKS 


Names of links. 


No 


CL_$WILD_EXCLUSIVE 


Only the highest directory 

of a given wildcard. This is useful for 

commands that operate on entire 

directories such as COPY_TREE. 

Since it operates on all 

subdirectories, there's no 

need to match further. 


No 


CL_$WILD_CHASE_LINKS 


Files and directories pointed to by links. 


No 


CL_$WILD_FIRST 


Only the first name of a given 
wildcard rather than expanding 
all names. 



f ~\ 



1.3.3. Example of Initialising the CL Manager 

Normally, you initialize the CL manager with CL_$INIT so that CL can parse the command line 
automatically. (See Example 1.7 for a sample program using CL__$INIT.) Examples in this 
section show how to initialize the CL manager with CL_$SETUP, and supply the lines to parse. 
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Example 1-2 is a program segment using CL_$SETUP to initialize the CL, and 
CL_ SPARSE __ LINE to supply the arguments for parsing. Instead of reading the command line 
for arguments, this program asks the user to supply a filename that contains the arguments to 
parse. It gets the file with STREAM calls, and then parses each line in the file with 
CL $PARSE LINE. 



program cl_parse_line; 



Xnolist; 
^include 
Xinclude 
^include 
^include 
^include 
^include 
fllist; 



' /sys/ins/base . ins . pas ' ; 
' /sys/lns/streams . ins . pas ' 
'/sys/ins/cl . ins . pas * ; 
' /sys/ins/vf mt . ins . pas ' ; 
' /sys/ins/pgm . ins . pas ' ; 
'/sys/ins/error . ins . pas * ; 



CONST 

program_name = 'cl_parse_line' ; 



VAR 




pathname 


name_$pname_t : 


name len 


integer; 


buf 


name_$pname_t ; 


ret_ptr 


~name_$pname_t ; 


ret len 


integer32; 


seek_key 


stream $sk t; 


stream id 


stream $id t; 


status 


status $t; 



PROCEDURE check_status; < Error handling procedure 
BEGIN < Main = 




■C Initialize CL with the default options, but don't parse the command line. > 
cl_$setup([] . program_name. sizeof (program_name)) ; 

■C Set wildcard options. Note, if you want more than the default wildcard 
options, you must specify all the wildcard options that you want. > 

cl_$set_wild_options ( [cl_$wild_files. 

cl_$wild_dirs. 
cl~$wil delinks. 
cl_$wild_first] ); 

< Ask user for the file containing the lines . > 

writeln (' Enter the file containing the command line arguments.' ); 



Example 1-2. Initialiiing CL with CL_$SETUP and CL_ SPARSE _ LINE 
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vfmt_$read2 ( 'JJ""Xeka%. *. count, status, pathname, name_len) ; 
check__status; 

{ Open file to parse and get lines. > 

stream_$open ( pathname, name_len. stream_$read. stream_$no_conc_write, 

stream_id, status ); 
check_status; 

WHILE (status. all = status_$ok ) DO BEGIN { Read lines until end-of-file. > 

stream_$get_rec( stream_id. addr(buf). sizeof(buf), ret_ptr. 
ret_len, seekjcey. status ) ; 

IF (status. code = stream_$end_of_file) AND 

(status . subsys = stream_$subs) THEN EXIT; 
check_status; 

< Parse the line before the NEWLINE character. > 

cl_$parse_line* ( ret_ptr". 

ret len -1 ) ; 



END; < while > 



stream_$close ( stream_id. status ); 
check status; 



END, 



Example 1-2. Initialising CL with CL_$SETUP and CL_ SPARSE _ LINE, Cont. 

While CL_ SPARSE __ LINE is useful for getting command line arguments from a file, 
CL_ SPARSE _ INPUT is useful for getting command line arguments interactively. The 
advantage of using CL_ SPARSE _ INPUT over CL_ SPARSE _ LINE is that it gets the line to 
parse and parses it in one step. (CL__ SPARSE _ LINE requires that you supply the line to 
parse.) 

Example 1-3 is an example of initializing the CL with CL_$SETUP and CL_ SPARSE _ INPUT. 



program cl_parse_input; 




Xnolist; 






^include 


'/sys/ins/base . ins 


. pas * ; 


^include 


'/sys/ins/str earns . 


ins . pas ' ; 


^include 


' /sys/ins/cl . ins . pas * ; 


^include 


' /sys/ins/vf mt . inc 


i.pas'; 


Xinclude 


'/sys/ins/pgm. ins . 


pas' ; 


Xinclude 


' /sys/ins/error . ins . pas 


Xlist; 






CONST 






program 


_name = •cl_parse_ 


input ' ; 



Example 1-3. Initialising CL with CL_$SETUP and CL_ SPARSE _ INPUT 
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ok 


: boolean 


null line 


: boolean 



BEGIN { Main > 

i Initialize the CL. but don't parse the command line. > 

cl_$setup ( [cl_$nojnatch_error] . < Terminate program when wildcards 

do not match any existing pathname. > 
program_name . < Name of program > 
sizeof (program_name) ) ; { Length of program name > 

■C Get the line to parse from standard input. > 

writeln (' Enter a command option or NEWLINE. ' ); 

i Parse the input. > 

ok := cl_$parse_input ( stream_$stdin. 

null_line ) ; 

IF null_line THEN 

writeln ('No input. Terminating program.'); 



END. 



Example 1-3. Initialising CL with CL_$SETUP and CL_$PARSE_ INPUT, Cont. 



1.4. Getting Flags 

After initializing the CI. manager, you usually check for any flags the user might have specified. 
The three CL calls that check for flags are the following: 

CL_$GET_FLAG 

Checks for a specified flag, marks it used, and counts the number of tokens 
following it, up to the next flag or the end of the list. 

CL_$CHECK_FLAG 

Checks for a specified flag, marks it used, and checks for correct number of 
tokens following it. 

CL_$GET_ENUM_FLAG 

Scans the token list for one of several flags the caller might have specified. It 
counts the number of tokens following it, up to the next flag or the end of the 
list. 

Your program can accept an abbreviated or full version of any flag by using brackets. For 
example, the string "-br[ief]" allows the user to specify either "-br" or "-brief." CL will return 
an error if the user specifies "-brie." 
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NOTE: You must use lowercase letters when defining flags with a GET_FLAG 
system call, CL will not recognize uppercase letters. However, 
the user can type either uppercase or lowercase letters. 

Another way to get arguments associated with a flag is to specify CL_$NEXT as the first 
argument in the CL_$GET_ARGS or CL__$GET_NAME system calls. See Section 1.5 for 
details. 

CL_$GET_FLAG and CL_$GET_ENUM_FLAG returns the number of tokens following the 
flag, up to the next flag. Note that these calls count the number of tokens on the command line 
only. The count does NOT include names expanded from wildcards. 

Normally, you use the GET_FLAG calls to get the flags from the token list before getting the 
names. In this case, after you make the calls to get the flags, you call 
CL_$CHECK_ UNCLAIMED. CL_$CHECK_ UNCLAIMED checks for any invalid flags the 
user might have specified. CL prints an error message on error output and aborts the program if 
it finds any unclaimed flags. 

There is one case where you might not want to call CL_$CHECK_ UNCLAIMED: When you 
use the CL_$GET_ FLAGGED _DERIVED_ NAME call to associate a flag with a particular 
name, you cannot call CL_$CHECK_UNCLAIMED before getting the names. For more 
information on this call, see Section 1.5. 

Sections 1.4.1 and 1.5.1 include Pascal examples of getting flags. Section 1.4.1 shows how to use 
the CL_$GET_ENUM_FLAG system call to define synonymous options that require the same 
program action. Section 1.5.1 shows how to get an argument associated with a specific flag. See 
Section 1.7 for a sample program using other GET__FLAG system calls. 



1.4.1. Example of Handling Synonymous Flags with CL_$GET_ENUM_FLAG 

Example 1-4 shows how to use the CL__$GET_ENUM_FLAG system call to define 
synonymous options that require the same program action. The CL_$GET_ENUM_FLAG 
allows you to specify an action if the user typed one of several flags. For example, the flags 
"-error" and "-fault'* might both require the same action. Each time you call 
CL_$GET_ENUM_FLAG system call, CL looks for the specified flags on the token list. If it 
finds any flag specified, it returns the index of the flag in the list, and stops searching. If it does 
not find a specified flag, it returns a zero. 

You can find out which flag the user actually typed in one of the the following ways: You can 
manipulate the index, since the CL__$GET_ENUM__FLAG call returns the index of the flag 
found. Or you can use the CL __$GET_ FLAG _ INFO system call to get the exact text that the 
user wrote. This example uses the CL _$GET_ FLAG _ INFO system call to see what the user 
actually typed. 
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PROGRAM cl_get_enum_flag; 
^include * /sys/ins/cl . ins . pas 



VAR 




report 


integer; 


number 


integer; 


flag_ptr 


"string; 


flag_len 


integer; 



< Report message if the user types the -mes[sage] or -rep[ort] flags. > 
report := cl_$get_enum_flag ( cl_$first. *-mes[sage] -rep[ort] X'. number ) 
{ Check for any undefined flags that the user might have typed. > 
cl $check unclaimed; 



IF report <> 
THEN BEGIN 

vriteln ( * This is the message you requested.*); 

cl_$get_flag_info (flag_ptr. 
f lag_len) ; 

writeln ( 'You typed the option: '. flag_ptr~ : f lag_len) ; 

END; 



Example 1-4. Using CL_$GET_ENUM_FLAG 



1.5. Reading Arguments 

After you get the flags to handle the options that the user specified, you get the remaining 
arguments on the token list. To do so, call one of the following system calls: 

CL_$GET_NUM 

Gets the next unused integer from the token list; converts it from a decimal to 
a 4-byte integer. 

CL_$GET_NAME 

Gets the first or next unused name from the token list. It expands wildcards. 

CL_$GET_ARG 

Gets the first or next unused argument from the token list, in character string 
format. 
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To get the arguments, you normally use the system call within a loop. This way, CL will 
continue to scan through the token list and return arguments until there are none left. 

Where the CL__GET calls begin the search depends on whether you set the first argument of the 
call to CL_$FIRST or CL_$NEXT. If you specify CL_$FIRST, CL begins searching from the 
head of the list each time it scans the token list. If you specify CL_$NEXT, it begins the search 
at the token pointer, which is set to the last token read. Normally, you use CL__$NEXT when 
you want the argument adjacent to the last token read. 

Sections 1.5.1 and 1.5.2 demonstrate ways to get arguments from the command line. 



1.5.1. Getting Arguments Associated with Flags 

You can get arguments associated with flags by using a either the CL__$GET_ARG, 
CL_$GET_NAME, or CL_$GET_NUM system call. 

Use CL_$GET_NAME if you expect a pathname, and CL_$GET_NUM if you expect a 
decimal number. If you want to accept both names or numbers, you can use CL_$GET_ARG. 
Since CL_$GET_ARG returns arguments in character string format, it will accept any 
argument. You can then convert the argument to the desired type. (The system call 
VFMT__$DECODE2 allows you to convert variables to another type.) 

Example 1-5 uses a CL_$GET_ARG, specifying CL_$NEXT as the first argument, so that 
CL_$GET_ARG will get the next argument after the "-copies" flag. Then it uses a 
VFMT_$DECODE system call to convert the string into a number. Note that we could have 
used CL_$GET_NUM to get the number directly, but CL_$GET_ARG assures that we get 
the token immediately following the flag. 



f 
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PROGRAM cl_get_args; 

^include '/sys/ins/cl. ins. pas' ; 

VAR 

num_args : integer; 
copies_string : string; 

copies_len : integer; 

copies_num : integer; 

hunoz : integer; 

hucares : integer; 

BEGIN < Main > 

IF cl_$get_flag ( '-cop[ies]'. num_args) THEN 
BEGIN 
IF NOT cl_$get_arg (cl_$next. 

copies_string. 
copies_len. 

sizeof (copies_string) ) 
THEN BEGIN 

writeln (' You must specify a number after "-copies."') 

pgm_$set_severity (pgm_$error) ; 

pgm_$exit 

END; 

< Convert copies_string to a number. > 

hunoz := vfmt_$decode2 C'XwdSS.'. < control string > 

copies_string. < To convert > 

copies^en, 

hucares, 

status, 

copies_num. < Converted > 

); 
END; 



Example 1-5. Getting Arguments Associated "with Flags 



1.5.2. Getting Derived Names 

If your program expects derived names, you can retrieve them using one of the following 
GET_DERIVED_NAME calls: 

CL_$GET_DERIVED_NAME 

Gets the next derived name associated with the last name returned from 
CL_$GET_NAME. 

CL_$GET_FLAGGED_DERIVED_NAME 

Gets the next derived name associated with the specified flag, and the last 
name returned from CL $GET NAME. 
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The following example shows how to use the CL__$GET_NAME, 
CL_$GET__DERIVED_NAME, and CL_$GET_FLAGGED_DERIVED_NAME system 
calls. This program expects two arguments, the second name is a derived name from the first 
argument. If the user supplied the "-list" flag, it prints out the second name. 



PROGRAM cl_get_f lagged_derived_names ; 



^include '/sys/ins/cl .ins. pas' ; 

VAR 

select : cl_$arg_select_t; 

count : integer; 

name : array [1..2] of name_$pname_t ; 

len : array [1..2] of integer; 

num_args : integer ; 

BEGIN < Main > 

■C Initialize the CL manager > 

•C Get flags except *-l[ist]' > 

< Get first argument. } 
select := cl_$first; 
WHILE cl_$get_name ( select. 

name [1] . 
len [l], 

sizeofCname [1])) 
DO BEGIN 

{ Get second argument. Check to see if it is a derived 
name. If it is. change name to derived name. > 

select := cl_$next; 

IF cl_$get_derived_name (name [2]. 

len [2]. 

sizeofCname [2])) 
THEN { Use FU manager to copy file > 



IF cl_$get_flagged_derived_name (*-l[ist]'. 

cl_$required. 
name [2] . 
len [2]. 

sizeof (name [2] ) ) 
THEN BEGIN 

IF len [2] = THEN < Command line error > 

vriteln ('You can supply only one derived name per flag. ') 
ELSE { Write name > 

vfmt_$write2 ( '%laX.*. 
name [2] . 
len [2] ); 
END; < begin > 
END; -C begin } 



Example 1-6. Reading Arguments from the Token List 
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1.6. Using Miscellaneous CL Calls 

The following is a list of miscellaneous CL calls that may be useful. The sample program in 
Section 1.7, as well as other examples in this chapter, shows how many of these calls work. 

Table 1-4. Miscellaneous CL System Calls 



System Call 


Description 


CL_$ VERIFY 


Verifies with the user that the program 
is supposed to operate on this name. 


CL_$SET_VERB 


Defines a verb for CL to display before 
each pathname when querying the user for 
names. 


CL_$GET_FLAG_INFO 


Returns the actual text of the previously 
returned flag. 


CL_$GET_NAME_INFO 


Returns information about the previously 
returned name. Determines whether the user 
supplied a full pathname or wildcard name on 
the command line. 


CL_$MATCH 


Compares a token against a specified string. 
Useful for cases where the command line 
logic is too complicated for CL to handle. 


CL_$GET_SET 


Creates a set to compare two 
character strings. 


CL_$SET_STREAMS 


Tells CL to use the specified streams 
as the default input and output channels. 


CL_$REREAD 


Marks the entire token list "unused" so the 
flags, names and arguments can be read again. 


CL _ $REREAD _ NAMES 


Marks all names "unused" so the 
names can be read again. The next 
CL_$GET_NAME call returns the 
first name on the list. 


CL _ $REREAD __FLAGS 


Marks all the flags "unused" so the 
flags in the token list can be read again. 
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1.7. Sample Program Using CL System Calls 

Example 1-7 uses CL system calls to parse the command line. It also uses File and Tree Utility 
(FU) system calls to copy a file. This program checks to see if the user specified a derived name, 
and copies the file to the new extension. For more information on FU system calls, see Chapter 
2, Using the File and Tree Utility (FU). 



PROGRAM cl_copy_file; 



%nolist; 
^include 
^include 
{{include 
^include 
^include 
^include 
%list; 



/sys/ins/ubase . ins . pas ' 
' /sys/ins/vf mt . ins . pas ' ; 
' /sys/ins/error . ins . pas ' 
' /sys/ins/pgm . ins . pas * ; 
' /sys/ins/cl . ins . pas * ; 
' /sys/ins/f u . ins . pas * ; 



CONST 

name_max = 32; 

program_name = *copy_derived_names*; 



VAR 



select 

count 

name 

len 

no_args 

status 



cl_$arg_select_t; 

integer; 

array [1..2] of name_$pname_t ; 

array [1..2] of integer; 

integer; 

status t; 



fu_opts : fu_$opt_set_t; 
fu context : fu $context t; 



{ Internal Procedure — Print_error - ==-i^ — :n^======:===== > 

PROCEDURE print_error; 

BEGIN 

pgm_$set_severity (pgm_$error ) ; 

pgm_$exit; 
END; 

{ ********♦*******#*************#*******************♦************** > 

BEGIN < Main > 

< Initialize CL with the default set of CL options. > 

cl_$init ( []. 

program_name . 

sizeof (program_name) ) ; 
fu $init; 



Example 1-7. Sample Program Using CL System Calls 
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fu_$set_prog_name ( program_name . sizeof (program_name) ); 
fu_opts := ([ fu_$coe. 

f u_$print_errors . 

f u_$dacl , 

f u_$subs ] ) ; 

{ Set verb for query in case user uses wildcards. > 

cl_$set_verb ('Copy*, 4 ); { Verb, length of verb > 

{ Allow the user to specify only 1 derived name after each wildcard name . > 
cl_$set_derived_count (1) ; 

{ Set the verify option that the user specifies . > 

IF cl_$get_flag 0-qa[]', no_args) THEN < Query all names } 

cl_$set_options ([cl_$verify_all]) ; 
IF cl_$get_flag C-qw[]'. no_args) THEN < Query names expanded by wildcards > 

cl_$set_options ([cl_$verify_wild]) ; 
IF cl_$get_flag C'-nqC]'. no_args) THEN < No Query > 

cl_$set_options ( [cl_$verif y_none] ) ; 

< Check for any invalid flags; exit if the user specified any. > 

cl_$check_unclaimed; 

< Get first name from the token list. > 

select := cl_$first; 

WHILE cl_$get_name ( select. 

name [1] . 
len [1]. 

sizeof (name [1])) 
DO BEGIN 

{ Get second name . Copy the first name to the 

second name . > 
select := cl_$next; 
IF cl_$get_derived_name ( name [2] . 

len [2]. 

sizeof (name [2])) 
THEN BEGIN 

f u_$copy_f ile ( name [1] . 
len [1]. 
name [2] . 
len [2] . 
f u_opts . 
fu_context. 
status ) ; 
IF status. all <> THEN 
BEGIN 

print_error; i FU error message > 
END; 
writeln ( name [2] :len[2]. ' created.*); < Confirm > 
END; •( then begin > 
END; < while > 
END. < Program > 



Example 1-7. Sample Program Using CL System Calls, Cont. 
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Output 

The following is a sample output from the above program. 



$ 


cl__copy_file.bin existing_file create_existing_file . 




create_existing_f ile created. 


$ 


cl_copy_file.bin no_file no_file_2 




? (copy_derived_names) "no_file" - name not found (OS/naming server) 


$ 


cl_copy__file.bin test_derived =.chek 




test_derived.chek created. 


$ 


cl_copy_file.bin test?* =.all -qa 




Verify wildcard "test?*": 




Copy "test2" ? y 




(file) "test2.all" deleted. <* Replaced contents of existing file. *> 




TEST2.all created. 




Copy "test2.all" ? n <* Queries file just created. *} 




Copy "test_fu.chek" ? y 




TEST_FU.CHEK.all created. 




Copy "test_tree" ? y 




? (copy_derived_names) "test_tree" - object must be a leaf (US/file utility) 



Example 1-7. Sample Program Using CL System Calls, Cont. 
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Chapter 2 
Using the File and Tree Utility 

The File and Tree Utility (FU) is a set of DOMAIN system routines that provides a consistent 
way to handle files and directories. By using FU system calls, your program can handle certain 
operations in the same way the Shell handles them so that you can provide your users with a 
consistent interface. FU allows you to perform the following operations: 

• Copy files. 

• Copy, merge, and replace files and directories. 

• Delete files and directories. 

• Compare directories. 

• Move files. 

• Make a unique pathname by appending today's date. 

Most of these system calls correspond to individual Shell commands. For more information on 
these commands, see the DOMAIN System Command Reference manual. 

This chapter provides an overview on using the FU subsystem and a sample program in Pascal. 
It concludes with system call syntax, data type, and error information. 

Since FU calls are often used in conjunction the Command Line Handler (CL), you might want to 
see Chapter 1, Parsing the Command Line for more information on the CL. 



2.1. System Calls, Insert Files, and Data Types 

To use the File and Tree Utility, use the system calls with the FU prefix. This chapter describes 
how most of these calls work. For details on FU call syntax, data types, and error messages, see 
Part II of this manual. 

When using FU system calls in your program, you must specify the appropriate insert file for the 
language your are using. The FU insert files are 

/SYS/INS/FU.INS.C for C. 

/SYS/INS/FU.INS.FTN for FORTRAN. 

/SYS/INS/FU.INS.PAS for Pascal. 



2.2. Overview of the FU System Calls 

The File and Tree Utility (FU) allows you to perform common operations on files and trees using 
DOMAIN system routines. When using FU, you often use the calls in the following order: 
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1. Initialize FU with FU_$INIT to allocate temporary storage space required to perform 
subsequent FU operations. 

2. Identify your program name with FU_$SET_PROG_NAME so that FU can 
identify your program by name when reporting errors. 

3. Use the various calls to operate on Hies and trees. 

4. Release the storage space used by FU with FU_$RELEASE_ STORAGE. 

Table 2-1 lists the operations you can perform on Hies and trees. It also lists each call's 
corresponding Shell command. 

Table 2-1. FU System Calls to Operate on Files and Trees 



System Call 


Corresponding 
Shell Command 


Operation 


FU_$CMP_TREE 


CMT 


Compares a source tree to a target tree. 


FU_$COPY_FILE 


CPF 


Copies a file from the source pathname to 
the target pathname. 


FU_$COPY_TREE 


CPT 


Copies, merges, and replaces files, 
directories, and links. 


FU_$DELETE_FILE 


DLF 


Deletes a specified file. 


FU _ $DELETE _ TREE 


DLT 


Deletes a tree and all its descendants. 


FU_$MOVE_FILE 


MVF 


Moves a file to a different location in 
the naming tree. 


FU_$RENAME_UNIQUE 


CHN-U 


Renames a pathname to create a unique 
name by appending today's date. 



The FU system calls require that you specify the source and, where applicable, target pathnames 
and pathname lengths. In addition, most calls require that you set FU options. The options 
control how FU performs the operation. For example, you can set FU options to list files as they 
are operated, or to set the ACL of the target files. 



2.2.1. Setting FU Options 

By setting FU options, you can provide users with options similar to those on the standard Shell 
commands. To do so, use the CL_$GET_FLAG system call to check for the option; then set 
FU options by assigning the appropriate predefined values to the FU__ OPTIONS variable. (See 
Example 2-1.) 

Table 2-2 lists the predefined FU options and their corresponding Shell options. 
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Table 2-2. FU Options To Provide Shell Command Options 



J 



FU Option 


Corresponding 
Shell Option 


Operation 


FU_$AFT_TME 


-AF DATE 


Operates on only those objects 
whose dtm (date/time last modified) 
is after the given date and time. 


FU_$BEF_TIME 


-BE DATE 


Operates on only those objects 
whose dtm (date/time last modified) 
is before the given date and time. 


FU_$COE 


Not specifying 
-AE (Abort on 
error ) 


If an error occurs while 
processing a file, continues to 
the next file. Most programs set 
this option. 


FU_$DACL 


-DACL 


Assigns default ACL to target files. 
Target gets the same ACL as the parent 
(destination) directory. 


FU_$DEL_WHEN_UNLKD 


-DU 


Deletes object when it becomes unlocked. 


FU_$FORCE 


None 


Forces a copy in FU_$MOVE if the 
source and target files are not located 
on the same volume. 


FU_$FORCE_DEL 


-F 


Forces deletion of a target during a 
replace operation if user has protect 
("P") rights. 


FU_$HELP 


None 


Displays detailed usage information. 
(This has no affect under AEGIS, but 
was added to provide help in a Boot 
Shell utility.) 


FU_$LIST_DIRS 


-LD 


Lists directories operated on. 


FU_$LIST_FILES 


-LF 


Lists files operated on. 


FU_$LIST_LINKS 


-LL 


Lists links operated on. 


FU_$LIST_D_DIRS 


-LDL 


Lists directories deleted as a 
result of a replace operation. 
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Table 2-2. FU Options To Provide Shell Command Options, Cont. 



FU Option 


Corresponding 
Shell Option 


Operation 


FU_$LIST_D_FILES 


-LF 


Lists files deleted as a result 
of a replace operation. 


FU_$LIST_D_LINKS 


-DLL -L 


Lists links deleted as a result 
of a replace operation. 


FU_$LIST_DEL 


-LDL -L 


Lists objects deleted as a result of 
a replace operation. This is 
obsolete for new development; use 
FU_$LIST_D_FILES, FU_$LIST_D_DIRS 
and FU_$LIST_D_LINKS instead. 


FU_$MERGE 


CPT -MS 


Merges source and target if both are 
directories. For files and links with the same 
name in source and target, it deletes the 
target, and replaces it with a copy of 
the source. 


FU_$MERGE_DST 


CPT-MD 


Merges source and target if both are 
directories. For files and links with 
the same name in source and target, 
the target remains unchanged. 


FU_$PRESERVE_DT 


-PDT 


Preserves the source dtm (date/time last 
modified) and dtu (date/time last used). 


FU_$PRINT_ERRORS 


None 


Prints errors on the error output stream. 
Use this to report FU errors. 


FU_$QUIT 


None 


Terminates the program. (This has 
no affect under AEGIS, but was added 
to provide help in a Boot Shell utility.) 


FU_$RENAME 


-CHN 


Changes the name of an existing object with 
the target pathname before creating a copy. 
If the target name exists, it appends 
today's date to the target pathname. 


FU_$REPLACE 


-R 


Replaces target with a copy of the source. 


FU_$SACL 


-SACL 


Assigns ACL of source file to target file. 
Target gets the same ACL as the source 
file. 


FU_$SUBS 


-SUBS 


Retains the source ACL for objects that 
belong to protected subsystems. 



V. 
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Example 2-1 shows how to set FU options. After initializing FU, the program sets up a default set 
of FU options. It then uses the CL_$GET_FLAG system call to check for the options on the 
command line. If the user specified an option, it sets the appropriate FU option. 



^include ' /sys/ins/base . ins . pas ' ; 
^include */sys/ins/cl. ins. pas' ; 
Xinclude '/sys/ins/fu. ins. pas'; 

CONST 

program_name = 'fu_handle_f lies' ; 



VAR 

pathname 

pathname_len 

num_args 

status 

fu__opts 



name_$pname_t ; 

integer; 

integer; 

status_$t; 

fu_$opt_set_t; 



BEGIN < Main > 

. < Initialize the CL. > 

{ Initialize FU. Set the program name so that FU calls can 
identify the program name when reporting errors. > 

fu_$init; 

fu_$set_prog_name ( program_name. 

sizeof (programjaame) ) ; 

i Set up default FU options. } 

fu_opts := ([ fu_$coe. < Continue on error > 
fu_$print_errors. < Print FU errors > 

fu_$dacl. i Target gets ACL of destination directory } 
fu_$subs ]); -C Retain source ACL for objects in protected 
subsytems > 

{ Get options from command line and set FU options accordingly. > 

IF cl_$get_flag C-r[]'. num_args) THEN { Replace target vith copy > 

fu_opts := fu_opts + [f u_$replace] ; < of source } 
IF cl_$get_flag C-sacl[]'. num_args) THEN 
BEGIN 

fu_opts := fu_opts - [f u__$dacl] ; < Remove default option > 
fu_opts := fu opts + [f u__$sacl] ; < Target gets same ACL as source > 
END; 
IF cl_$get_flag (*-dacl[]', num_args) THEN 

fu_opts := fu__opts + [f u_$dacl] ; < Target gets ACL of dest directory > 
IF (( [fu_$dacl. fu_$sacl] * fu_opts) = [fu_$dacl. fu_$sacl]) THEN 
BEGIN 

vriteln ('Invalid options: -dacl and -sacl are mutually exclusive.'); 
error_routine; 
END; 
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2.2.2. Releasing Storage with FU_$RELEASE_ STORAGE 

FU allocates read/write(RWS) storage space when copying files during the FU_$COPY_FE,E, 
FU_$COPY_TREE and FU__$MOVE_FILE routines. (It needs this space for tables to keep 
track of ACLs.) 

This storage gets released automatically when your program terminates. However, if your 
program performs numerous copy operations, we recommend that you call 
FU_$RELEASE_ STORAGE to release the storage more often. 



2.3. Sample Program Using the FU System Calls 

Example 2-2 is a sample program that uses FU system calls to perform common operations on 
files and directories. It also uses Command Line Handler (CL) calls to parse the command line. 
For more information on CL system calls, see Chapter 1, Parsing the Command Line. 

This program allows the user to perform various FU operations. It asks the user to specify which 
operation to perform, then it prompts the user for pathnames and options. 



program fu_nandling_files_trees; 



J&nolist; 
^include 
^include 
^include 
^include 
^include 
^include 
^include 
^include 
^include 
SSlist; 



' /sys/ins/base . ins . pas ' ; 
'/sys/ins/streams . ins .pas 
'/sys/ins/cl . ins . pas ' ; 
* /sys/ins/f u . ins . pas * ; 
Vsys/ins/vf mt . ins . pas * ; 
' /sys/ins/pgm . ins . pas ' ; 
* /sys/ins/error . ins . pas ' ; 
' /sys/ins/time . ins . pas ' ; 
' /sys/ins/cal . ins . pas ' ; 



CONST 

program_name 

VAR 
select 
pathname 
pathname_len 
num_args 
status 
command 
command_len 
ok 

null_line 
fu_opts 
fu_context 
fu_error 
fu error len 



= *fu_handling_files_trees 



cl_$arg_select_t; 

name_$pname_t ; 

integer; 

integer; 

statu8_$t; 

string; 

integer; 

boolean; 

boolean; 

f u_$opt_set_t ; 

fu__$context_t; 

name__$pname_t ; 

integer; 
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{ Internal Procedure — Check_status 

PROCEDURE check_status; 

BEGIN 



IF status. all <> status_$ok THEN 
BEGIN 

error_$print (status); 
pgm_$set_severity (pgm_$error) ; 
pgm_$exit; 
END; 

END; < check_status > 

< Internal Procedure — Get time -■-. '■■-. ir-— : 



PROCEDURE get__time ( OUT int_clock : time_$clock_t ) ; 



VAR 

readable_dt 

date_string 

date_len 

time_string 

time_len 

BEGIN 



cal_$timedate_rec_t ; 

string; 

integer; 

string; 

integer; 



< Convert command line date string to readable format. 
Date must be in year /month/day (85/09/15) format. > 

ok := cl_$get_arg ( cl_$next. date_string. date_len, sizeof (date_string) ); 

cal_$decode_ascii_date ( date_string. date_len, readable_dt .year. 

readable_dt .month, readable_dt .day. status ); 
check_status; 

{ Convert command line time string to readable format. 

Time must be in hr/min/sec 24-hour format (17:33:55). > 

ok := cl_$get_arg ( cl_$next. time_string. time_len. sizeof (time_string) ); 

cal_$decode_ascii_time ( time_string. time_le: readable_dt.hour. 

readable_dt. minute. readable_dt .second, status ); 
check_status; 

{ Convert readable date and time to internal time. > 

cal_$encode__time ( readable_dt. int_clock ); 
cal_$remove_local_of f set ( int_clock ) ; 

END; < get time > 
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•C Internal Procedure — Copy_f ile 



< Copies source pathname to target pathname. By default, the target gets 
the ACL of the destination directory, unless user specifies -SACL. 
User can also preserve source's dtm/dtu times by typing -PDT. } 

PROCEDURE copy_file; 

VAR 

new_pathname : name_$pname_t; 
new_pathname_len : integer; 

BEGIN 

•C Set wildcard options. > 

cl_$set_wild_options ( [cl_$wild_files] ); 

{ Reinitialize default FU options. } 

fu_opts := ([ fu_$coe, < Continue on error > 
fu_$print_errors. < Print FU errors > 

fu_$dacl. < Target gets ACL of destination directory > 
fu_$subs ]); < Retain source ACL for objects in subsytems > 



{ Get the filenames. > 



writeln; 

writeln 

writeln 

writeln; 

writeln; 

writeln 

writeln 

writeln 

writeln; 

writeln 

writeln 

writeln 

writeln; 

writeln 

writeln 

writeln; 



Enter the name of the file you want to copy, then 
the name of the new file you want created. '); 



'); 



Type "-r[eplace]" if you want to replace the target with '); 
the source. If target exists, it will be deleted. '); 
If it doesn*'t exist, it will be created. '); 

Type "-sacl" if you want the target file to have the '); 
same ACL as the source file; otherwise the target '); 
file will have the same ACL as its parent directory. ') 

Type "-pdt" if you want to preserve the source file*'s '); 
modification and used times. '); 



ok := cl_$parse_input ( stream_$stdin. nullJLine ); 

IF null_line THEN 

writeln ('No input. Type CTRL/Q to quit.'); 

■C Get keywords, set appropriate FU options. Check for any invalid keywords; 
and exit if user specified any. > 

IF cl_$get_flag C-r[eplace] '. num_args) THEN 

fu_opts := fu_opts + [fu_$replace] ; < Replace target with source > 
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IF cl_$get_flag ('-sacl[]'. num_args) THEN 
BEGIN " 

fu opts := fu_opts - [fu_$dacl]; < Remove default option > 

fu~opts := fu_opts + [fu_$sacl]; < Target gets same ACL as source > 

END; 
IF cl $get flag C-pdt[]\ num_args) THEN { Preserve source's > 

~ fu_opts := fu_opts + [f u_$preserve_dt] ; < modification and used times> 

cl_$check_unclaimed; 
< Get first argument. > 
select := cl_$first; 

WHILE cl $get_name ( select, pathname. pathname_len. sizeof (pathname) ) 
DO BEGIN 

< Get second argument and copy the file. > 
select : = cl_$next; 

IF cl $get_derived_name ( newjpathname. new_pathname_len. 

sizeof (newjpathname) ) 

THEN BEGIN 

fu_$copy_file (pathname. < Source file > 

pathname_len. < Length of source file > 

new_pathname . < Target file > 
new_pathname_len. < Length of target file > 

fu opts. < FU options in effect > 

fu~context. < Error context > 

status ) ; < Completion status > 
check_status; 

IF status. all = status_$ok THEN 

vfmt $write2 ( 'Copied to file named. "%a M %.' . 
~~ new pathname. new_pathname_len) ; 



END; -C then begin } 
END; i while > 

END; < copy_file > 

i Internal Procedure — Copy_tree ===== 



== > 



< Copies source pathname to target pathname . > 

PROCEDURE copy_tree; 

VAR 

new_tree : name_$pname_t ; 

new_tree_len : integer; 

bef time : time_$clock_t; 

aft time : time $clock t; 
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BEGIN 

{ Set verb for query in case user uses wildcards. > 

cl_$set_verb ('Copy*. 4); < Verb, length of verb > 

■C Set wildcard options. > 

cl_$set_wild_options ([cl_$wild_files. cl_$wild_dirs. cl_$wild_exclusive]) ; 

< Reinitialize default FU options. > 

fu_opts := ([ fu_$coe. < Continue on error > 

f u_$print_errors . < Print FU errors > 

fu_$dacl. < Target gets ACL of destination directory > 
fu__$subs ]); { Retain source ACL for objects in subsytems > 

{ Get the filenames . > 



writeln 

vriteln 

writeln; 

writeln 

vriteln 

writeln; 

writeln 

writeln 

writeln 

writeln; 

writeln 

writeln 

writeln; 

writeln 

writeln 

writeln; 

writeln 

writeln 

writeln; 



Enter the name of the directory you want to copy, then '); 
the name of the new directory you want created. '); 

Type "-ms[]" if you want to merge the source and target '); 
if both are directories. '); 

Type "-r[eplace] " if you want to replace the target with '); 
the source. If target exists, it will be deleted. '); 
If it doesn'*t exist, it will be created. '); 

Type "-bef date time" if you want to copy only those files '); 
modified before a certain date and time. '); 

Type "-aft date time" if you want to copy only those files '); 
modified after a certain date. '); 



Use this format for date time: yr /month/day hr:min:sec 
Example: -bef 85/11/27 12:35:09 source target *); 



•); 



ok := cl_$parse_input ( stream_$stdin. null_line ); 

IF null_line THEN 

writeln ('No input. Type CTRL/Q to quit.*); 

i Get Keywords, set appropriate FU options, then check for any invalid 
keywords; exit if user specified any. > 

■C Get flags and set appropriate FU options. > 

IF cl_$get__flag C-ms[]*. num_args) THEN < Merge target and source 

fu_opts := fu_opts ♦ [fu_$merge] ; if they are directories > 

IF cl_$get_flag C-r[eplace] '. num_args) THEN 

fu_opts := fu_opts + [f u_$replace] ; < Replace target with source > 
IF cl $get_flag C-befC]*. num^args) THEN 
BEGIN 

get_time ( bef^time ) ; < Operate on files modified 

fu opts := fu_opts + [f u__$bf__time] ; before date > 
END; 
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J 



IF cl_$get_flag (*-aft[]'. num args) THEN 
BEGIN 

get_time ( aft_time ); < Operate on files modified 
fu_opts := fu_opts + [fu $af time]; after date > 
END; 
cl_$check_unclaimed; 


-C Get first argument. > 






select := cl_$first; 






WHILE cl_$get_name ( select. 
DO BEGIN 


pathname , pathnam 


B_len. sizeof (pathname) ) 


< Get second argument 


and copy the tree 


. > 


select := cl_$next; 






IF cl_$get_derived_name ( new_tree. new 
THEN BEGIN 

fu_$copy_tree ( pathname. 

pathname_len. 

new_tree. 

new_tree_len. 

fu_opts. 

bef_time .high. 

aft_time.high. 

fu_error. 

fu_error_len. 

status ) ; 
check_status; 


_tree_len. sizeof (new_tree ) ) 

< Source pathname > 

< Source pathname length } 
{ Target pathname } 

< Target pathname length > 

< Options > 

< Before time > 

< After time > 

< Error pathname > 

•C Error pathname length } 

< Completion status > 


IF status. all = status_$ok THEN 

vfmt_$write2 ( 'Copied to directory named. "%a" %.' . 
new_tree. new_tree_len ); 


END; { then begin 
END; < while } 


> 




END; < copy_tree > 




PROCEDURE delete_file; 






< Delete specified file. > 






VAR 

force : boolean; 
del_unlkd : boolean; 
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BEGIN 

{ Set wildcard options. > 

cl_$set_wild_options ( [cl_$wild_files] ); 

{ Reinitialize default FU options. > 

fu_opts := ([ fu_$coe, < Continue on error > 
fu_$print_errors. < Print FU errors > 

fu_$dacl. { Target gets ACL of destination directory > 
fu_$subs ]); < Retain source ACL for objects in subsytems > 

{ Get the filename. } 

writeln Enter the name of the file(s) you want to delete. '); 
writeln (' Type -f[orce] if you want to force the delete. '); 
writeln (' Type -du if you want to delete a locked object. '); 

ok := cl_$parse_input ( stream_$stdin. null_line ); 

IF null_line THEN 

writeln ('No input. Terminating program.*); 

< Get keywords and check for any invalid keywords; 
exit if user specified any. > 

force := cl_$get_flag ('-f[orce]'. num_args) ; 
del_unlkd := cl_$get_flag C'-duC]'. num_args) ; 

cl_$check_unclaimed; 
■C Set verb for query in case user uses wildcards . > 

cl_$set_verb ('Delete'. 6); { Verb, length of verb > 
{ Get first argument. } 

select := cl_$first; 

WHILE cl_$get_name ( select, pathname. pathname_len. sizeof (pathname) ) 
DO BEGIN 

fu_$delete_file ( pathname. i File to be deleted > 
pathname_len. < Length of file } 
force. i 7f TRUE, deletes file 

if user has owner rights, 
but not delete rights. > 
del_unlkd. i If TRUE, deletes file 

even if it is locked. > 
status ) ; 
check_status; 
IF status. all = status__$ok THEN 

vfmt_$write2 ( 'Deleted file named, "jja" %.' . 
pathname . pathname_len) ; 
END; < while > 
END; < delete file > 
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< Internal Procedure — Delete_tree ; — -.==-:. :- ■ ... ■■■.■■■■■■ --^- > 

PROCEDURE delete_tree; 

< Delete specified directory. } 

BEGIN 

< Set verb for query in case user uses wildcards . > 

cl_$set_verb ('Delete* , 6 ); < Verb, length of verb > 

< Set wildcard options. > 

cl_$set_wild_options ( [cl_$wild__f iles. cl_$wild_dirs. cl_$wild_exclusive] ) 

< Reinitialize default FU options. > 

fu_opts := ([ fu_$coe. < Continue on error > 

fu_$print_errors. < Print FU errors > 

fu_$dacl. i Target gets ACL of destination directory > 
fu_$subs ]); < Retain source ACL for objects in subsytems > 

{ Get the filenames. > 

writelnj 

writeln (' Enter the name of the directory you want to delete. '); 

writeln (' Note that you will delete all the files, links and '); 

writeln (' subdirectories located in this directory. '); 

writeln; 

writeln (' Type "-l[ist]" if you want to list all the objects as '); 

writeln (' they are deleted. '); 

writeln; 

writeln (' Type "-If" if you want to list only files as they are deleted.') 

writeln; 

ok := cl_$parse_input ( stream_$stdin. null_line ); 

{ Get keywords, set appropriate FU options, then check for 
any invalid keywords; exit if user specified any. > 

IF null_line THEN 

writeln ('No input. Type CTRL/Q to quit.'); 
IF cl_$get_flag (*-l[ist]'. num_args) THEN 
fu_opts := fu_opts + [fu_$list_links. 

fu_$list_dirs. 
fu_$list_f lies] ; 
IF cl_$get_flag C-lf[]' # num_args) THEN 

fu__opts := fu_opts + [fu_$list_f iles] ; 

cl_$check_unclaimed; 

•C Get first argument. > 

select := cl $first; 
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WHILE cl_$get_name ( select, pathname, pathname_len. sizeof (pathname) ) 
DO BEGIN 

fu_$delete_tree ( pathname, 

pathname_len. 
f u_opts . 
fu_error, 
fu_error_len. 
status ) ; 
check status; 



< Source pathname > 

< Source pathname length > 

< Options > 

< Error pathname > 

i Error pathname length > 

< Completion status > 



IF status. all = status_$ok THEN 

vfmt_$write2 ( 'Delete directory named. "Xa" %.' . 
pathname . pathname_len ) ; 



END; i while > 
END; < delete_tree > 
{ Internal Procedure — Compare_tree 



{ Compare source tree to target tree . > 

PROCEDURE compare_tree; 

VAR 

tar_pathname : name_$pname_t; 
tar_pathname_len : integer; 

BEGIN 

{ Set verb for query in case user uses wildcards. > 

cl_$set_verb ('Compare* , < Verb > 

7 ) ; -C Length of verb > 

i Set the wildcard options . > 

cl_$set_wild_options ( [cl_$wild_f iles. cl_$wild_dirs, cl_$wild_exclusive]) ; 

•C Reinitialize default FU options. > 

fu_opts := ([ fu_$coe, < Continue on error } 

fu__$print_errors. < Print FU errors > 

fu_$dacl, < Target gets ACL of destination directory > 
fu__$subs ]); < Retain source ACL for objects in subsytems > 

{ Get the filenames. > 

writeln (' Enter the name of the two directories you want to compare. '); 

writeln (* Type "-1 or -list" if you want to compare all the directories ') 

writeln (' and files. '); 

writeln; 

writeln (' Type "-If - if you want to compare all the files. '); 

writeln; 
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ok := cl__$parse_input ( Btream_$stdin. null_line ); 

IF null_line THEN 

writeln ('No input. Type CTRL/Q to quit.*); 

< Get keywords, set appropriate FU options, then check for any invalid 
keywords; exit if user specified any. > 

IF cl_$get_flag C-l[ist]*. num_args) THEN 
fu_opts := fu_opts + [fu_$list_links. 

fu__$list_dirs. 
fu_$list_f iles] ; 
IF cl_$get_flag C-lfC]'. num_args) THEN 

fu_opts := fu_opts + [f u_$list_f iles] .■ 
cl_$check_unclaimed; 
{ Get first argument. > 
select := cl_$first; 

WHILE cl_$get_name ( select, pathname. pathname_len. sizeof (pathname) ) 
DO BEGIN 

< Get second argument and copy the tree . > 

select := cl_$next; 

IF NOT cl_$get_derived_name ( tar_pathname . tar_pathname_len, 

sizeof (tar_pathname ) ) 
THEN BEGIN 

vfmt_$write2 ( 'No pathname to compare with "%&' %. 

pathname . 

pathname_len ) ; 
pgm_$set_severity ( pgm_$error ); 
pgm_$exit 
END; < then begin > 



iu_$cmp_tree ( pathname, 

pathname_len. 



< Source pathname > 

< Source pathname length } 
tar_pathname , < Target pathname > 
tar_pathname_len, < Target pathname length } 



f u_opts . 
f u_error . 
fu_error__len. 
status ) ; 



< Options > 
•i Error pathname > 

i Error pathname length > 

< Completion status > 



check_status; 
END; < while > 
END; < compare_tree > 
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< Internal Procedure — Move file 



== > 



PROCEDURE move_file; < Move file to another location. > 

VAR 

tar pathname : name_$pname_t ; 
tar_pathname_len : integer; 

BEGIN 

< Set verb for query in case user uses wildcards. > 



cl_$set_verb ('Move', 4 ); 

cl $set derived- count (1) ; 



< Verb, length of verb > 



< Set wildcard options. > 

cl_$set_wild_options ( [cl_$wild_f iles] ) ; 

< Reinitialize default FU options > 

fu_opts := ([ fu_$coe. < Continue on error > 

fu_$print_errors. -C Print FU errors > 

fu~$dacl. < Target gets ACL of destination directory > 
fu__$subs ]); { Retain source ACL for objects in subsytems > 

< Get the filenames. > 



writeln (' 
writeln (' 
writeln; 
writeln (' 
writeln (' 
writeln (' 
writeln (* 
writeln (' 
writeln (' 
writeln; 



Enter the name of the file you want to move, then '); 
the pathname where you want to move it to. '); 

Type "-l[ist]" if you want to list the files. '); 

Type "-r [eplace] " to replace the target file with the ') 

source file if it exists. '); 
Type "-chn" to change the name of the target file. '); 
Type "-fdl" to delete the target file if it exists. '); 

if you have owner rights. '); 



ok := cl__$parse_input ( stream_$stdin. null_line ); 

IF null_line THEN 

writeln ('No input. Type CTRL/Q to quit.'); 

•C Get keywords, set appropriate FU options, then check for any invalid 
keywords; exit if user specified any. > 



IF cl_$get_flag 

fu_opts 
IF cl_$get_flag 

fu_opts 
IF cl_$get_flag 

fu_opts 
IF cl_$get_flag 

fu_opts 



C-l[ist]'. num_args) THEN 
:= fu_opts + [f u__$list_f iles] ; 

(' -r [eplace] '. num__args) THEN 
:= fu_opts + [f u_$replace] ; 

C-chn[]'. num_args) THEN 
:= fu_opts + [f u_$rename] ; 

C-fdl[]'. num_args) THEN 
:= fu_opts + [fu_$force_del] ; 
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cl_$check_unclaimed; 

< Get first argument. > 

select := cl_$first; 

WHILE cl_$get_name ( select, pathname, pathname_len. sizeof (pathname) ) 
DO 
BEGIN 

< Get second argument and copy the tree. > 

select := cl_$next; 

IF cl_$get_derived_name ( tar_patbname,tar_pathname_len. 

sizeof (tar_pathname ) ) 
THEN 
BEGIN 

fu_$move_file ( pathname. { Source pathname } 

pathname_len. < Source pathname length > 
tar_pathname . < Target pathname } 
tar__pathname_len. i Target pathname length > 
fu__opts. < Options > 
fu_context. { Error pathname > 
status ) . < Completion status } 
check_status; 
END; { then begin > 
END; { while > 

END; < move file > 



{ Internal Procedure — Rename file 






{ Rename a pathname to create a unique pathname . > 

PROCEDURE rename_file; 

BEGIN 

{ Reinitialize default FU options. > 

fu_opts := ([ fu_$coe. { Continue on error > 

fu_$print_errors. i Print FU errors > 

fu_$dacl. < Target gets ACL of destination directory } 

fu_$subs ]); < Retain source ACL for objects in subsytems } 

{ Get the filename. > 

writeln (' Enter the name of the file you want to make unique. It '); 
writeln (' will append a period and today's date to the filename. '); 
writeln; 
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ok := cl_$parse_input ( stream_$stdin. null_line ); 

IF null_line THEN 

writeln ('No input. Type CTRL/Q to quit.'); 

{ Get first argument. > 

select := cl_$first; 

WHILE cl_$get_name ( select, pathname, pathname_len. sizeof (pathname) ) 
DO BEGIN 

fu_$re'name_unique ( pathname. ■( Source pathname > 

pathname_len. < Source pathname length > 

fu_opts. { Options > 

status ) ; < Completion status > 
check_status; 

END; < while > 

END; i rename file > 



< = 



=== } 



BEGIN < Main > 

< Initialize the CL. but don't parse the command line. > 

cl_$setup ( [cl_$no_match_error. < Terminate program when wildcards 

do not match any existing pathname . > 
cl_$verify_all] . < Verify all names with user. > 
program_name . i Name of program > 
sizeof (program_name)) ; { Length of program name > 

•C Initialize FU. set the program name so that FU calls can 
identify the program name when reporting errors. > 

fu_$init; 

fu_$set_prog_name ( program_name . 

sizeof (program_name) ); 

{ Set up default FU options. > 

fu_opts := ([ fu_$coe. -C Continue on error > 
f u_$print_errors . i Print FU errors > 

fu__$dacl. < Target gets ACL of destination directory > 
fu__$subs ]); < Retain source ACL for objects in subsytems > 



< Get the line to parse from standard input. > 

writeln; 

writeln ( 'This program allows you to handle files and trees. '); 

writeln; 
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REPEAT < user types CTRL/Q > 






writeln ( 'Enter the option and files you want to operate on. '); 




writeln ( 'Type "cpf to copy a file. '); 




writeln ( 'Type "cpt" to copy a tree. '); 




writeln ( 'Type "dlf" to delete a 


file. '); 




writeln ( 'Type "dlt" to delete a 


i tree. ') ; 




writeln ( 'Type "mvf" to move a file. '); 




writeln ( 'Type "cmt" to compare a 


i tree. ') ; 




writeln ( 'Type "ren" to rename a 


file. '); 




< Parse the input . > 






ok := cl_$parse_input ( stream_$stdin. 




null_line 


); 




IF null line THEN 






BEGIN 






writeln ('No input. Terminating program.'); 




pgm $exit; 






END; 






< Get keywords, then check for any invalid keywords; 




exit if user specified any. > 






IF cl $get_arg (cl_$first. command, command len. sizeof (command)) THEN 




BEGIN 






IF cl_$match Ccpf[]'. command. 


command_len) THEN 




copy_f ile; 






IF cl_$match (*cpt[]'. command. 


command_len) THEN 




copy_tree ; 






IF cl_$match C'dlf[]'. command. 


command^len) THEN 




delete_f ile; 






IF cl_$match ('dlt[]'. command. 


command_len) THEN 




delete_tree; 






IF cl_$match C*mvf[]'. command. 


command_len) THEN 




move_f ile; 






IF cl_$match ('cmt[]'. command. 


command_len) THEN 




compare_tree ; 






IF cl_$match Cren[]'. command. 


command_len) THEN 




rename_f ile; 






END; 






UNTIL FALSE; { User types CTRL/Q > 




. 


END. 
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Chapter 3 
Logging In and Changing the Registry 



The LOGIN Manager is a set of DOMAIN system routines that allows you to tailor a log-in 
operation or change a user's registry ACCOUNT file. You might want to change a log-in 
operation to provide stricter log-in requirements You can change a registry ACCOUNT file to 
change a user's password or home directory. 

Before using the LOGIN system calls, you should be familiar with registry PERSON, PROJECT, 
ORGANIZATION (PPO) and ACCOUNT files. For more information, see the Administering 
Your DOMAIN System manual. 



3.1. System Calls, Insert Files, and Data Types 

To use the LOGIN manager, use the system calls with the prefix LOGIN. This chapter describes 
how most of these calls work. For details on LOGIN call syntax, data types, and error messages, 
see Part II of this manual. 

When using LOGIN system calls in your program, you must specify the appropriate insert file for 
the language your are using. The LOGIN insert files are 

/SYS/INS/LOGIN.INS.C for C. 

/SYS/INS/LOGIN.INS.FTN for FORTRAN. 

/SYS/INS/LOGIN.INS.PAS for Pascal. 

In addition, you might need to bind your program with the source file, NLOGIN.BIN because the 
entry points to most LOGIN system calls are not in a global library. 



3.2. Overview of the LOGIN System Calls 

The LOGIN subsystem contains system calls that allow you to write a tailored log-in procedure, 
or change a user's password or home directory. 

To tailor a log-in operation, use the system call, LOGIN __$LOGIN. 

To change a user's registry ACCOUNT file, use the LOGIN system calls: 

• LOGIN__$OPEN 

• LOGIN_$CHPASS 

• LOGIN_$CHHDIR 

• LOGIN_$CKPASS 

• LOGIN_$CLOSE 

Sections 3.3 and 3.4 describes the two log-in operations. 
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3.3. Tailoring a Log-In Operation 



/-~ 



Use the LOGIN_$LOGIN system call to tailor a LOGIN operation. For example, you can require 
users to have different PPO identities to access a particular program. That is, the user 
DARLENE.MARKETING might need to log in as 

DARLENE.MARKETING.NEW__PRODUCTS.SPHINX to have full rights to an object.' 

To write your own LOGIN procedure using the LOGIN_$LOGIN system call, you supply 
LOGIN _$LOGIN with an open stream, and pointers to your own log-in I/O routines. Your 
program passes an open stream to LOGIN _$LOGIN, LOGIN__$LOGIN checks the password the 
user supplied against the registry's password for that PPO. If they match, the program logs the 
user in. 

NOTE: Your program must be a protected subsystem in the LOGIN subsystem. 
(See the DOMAIN System User's Guide for more information 
on protected subsystems.) 

Since LOGIN __$LOGIN is designed to be device-independent, you must supply your own 
input/output routines. LOGIN_$LOGIN requires four routines: a read, write, help, and an open 
log routine. LOGIN_$LOGIN uses these routines to get the user's input and display messages. 

Example 3-1 shows how you declare pointers to your routines. The second parameter, 
LOGIN__$LOG__EVENTS, indicates that you are supplying an open log routine so that 
LOGIN_$LOGIN records any user's attempts to log in. 

To get the addresses of these routines in Pascal, you must put the I/O routines in a module 
separate from your main log-in program. Bind the two binary files to execute your log-in 
program. 



{ Get addresses of external I/O procedures for LOGIN_$LOGIN . > 



login_procedures . pread 
login_procedures . pwrite 
login_procedures . help 
login_procedures .open_log 



= addr(my_read) ; 
= addr(my_vrite) ; 
= addr(my_help) ; 
= addr(my_open_log) 



IF NOT login__$login ( stream_in. { Stream ID where user will log in 

[login_$log_events] . { Logging events > 
login_procedures. < Address of your I/O routines 
status ) < Completion status > 

THEN 

IF (status. all = login_$err_shut) THEN 
BEGIN 

err_exit (status) ; 
END; 



Example 3-1. Declaring External I/O Routines for LOGIN_$LOGIN 

You are not restricted in how you write your I/O routines, except that each routine's parameters 
must correspond to those arguments that LOGLM_$LOGIN expects. The routines must also 
perform the operation that LOGIN _$LOGIN expects: 
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• MY _ READ gets the PPO string and password for logging in. It also prompts for a 
new password if the user types "-P", or for a new home directory if the user types 
"-H." If MY _ READ does not provide a way to get this information, 
LOGIN_$LOGIN prompts for it. 

• MY __ WRITE writes any error messages to output. 

• MY__HELP provides a message for when a user types "-h[elp]" at the log-in prompt. 

• MY__OPEN_LOG records all sucessful and unsuccessful log-in attempts if you 
specified the LOGIN_$LOG_EVENTS option when you called LOGIN_$LOGIN. 

When you specify LOGIN __$LOG_EVENTS, LOGIN_$LOGIN calls your log event routine at 
each log-in attempt. It passes the name of its log file to your routine, opens the file, records the 
event, and closes the file. LOGIN_$LOGIN will record both sucessful and unsucessful log-in 
attempts in the file, 'NODE _DATA/SIOLOGIN_ LOG. Your log-in routine can create its own 
log file simply by ignoring the file name that LOGIN_$LOGIN passed. However, note that 
LOGIN _$LOGIN will close your file after each log-in attempt. 

* 
Example 3-2 shows how to write the parameters for the I/O routines in Pascal. 



< Login read procedure 

■C LOGIN_$LOGIN calls this procedure to get a PPO string and password. Also, 
if the user types a "-P" or "-H." it prompts for a new password or home 
directory respectively. This procedure can supply the prompt string that 
LOGIN_$LOGIN will use to prompt for PPO and password. > 



FUNCTION my_read( 
IN stream 

OUT inbuf 

IN inlen 
IN pstr 
IN plen 
IN echo 



IN fillbuf 
IN fillbuflen 

) : integer; 

EXTERN; 



stream_$id_t; < 
UNIV login_$string_t; i 



integer; 

UNIV login_$string_t; 

integer; 

boolean; 



UNIV login_$string_t; 
integer 



Stream ID on which to log user 

in, usually stream_$stdin > 

Returns string to supply to 

LOGIN_$LOGIN > 

Maximum length of string buffer > 

Prompt string > 

Length of "pstr" > 

Indicates whether to echo characters 

Used to prevent the DM from 

displaying a password. > 
Not used, specific to the DM > 
Not used, specific to the DM > 
Returns length of the PPO string > 



< Login write procedure 



PROCEDURE my_write( 
IN stream 

IN pstr 
plen 
); 

EXTERN; 



stream_$id_t; { Stream ID on which to display user's 

output, usually stream_$stdout > 
UNIV login_$string_t; { Message to write > 
integer {Length of message } 
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< Login help procedure 



{ LOGIN_$LOGIN calls this procedure when a user types h[elp] at the 
prompt . > 



PROCEDURE my_help( 

IN stream : stream $id t 



EXTERN; 

< Login open log procedure 



{ Stream ID on which to write 
help message > 



i LOGIN_$LOGIN calls this procedure whenever a user attempts to log in, 
if the LOGIN_$LOG_EVENTS option was set. > 

FUNCTION my_open__log( 

IN log_file : UNIV login_$string_t; { Pathname of log file > 

IN log_flen : integer; < Length of "log_file" > 

OUT logstr : stream_$id_t < Returns stream ID of log file > 

) : boolean; { Returns TRUE if successful > 
EXTERN; • 
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3.3.1. Sample Program Using LOGIN__$LOGIN 

Examples 3-3 and 3-4 show how to use the LOGIN _$LOGIN system call in Pascal. The first 
example is a main procedure that performs a log-in operation. The second example is a module 
containing the input/output routines for LOGIN __$LOGIN. 

The main program gets the addresses of the external I/O routines, and calls LOGIN _$LOGIN. 
Note that when calling LOGIN_$LOGIN, the LOGIN _$LOG_ EVENTS option was specified, 
so that LOGIN _$LOGIN will record each log-in attempt. 

LOGIN_$LOGIN calls MY_READ when it needs log-in information — the login string and 
password, and, if the user typed a "-P," or "-H," the new password or home directory 
respectively. It calls MY_WRITE when it needs to write error messages. It calls MY__HELP 
when the user asked for help at the prompt. It calls MY_OPEN_LOG, (because we set the 
LOGIN_$LOG_EVENTS option), after each log-in attempt. When calling MY_OPEN_LOG, 
it records whether the attempt was successful or not, then closes vhe file. 

Each call to MY_OPEN_LOG passes an open stream to LOGIN_$LOGIN. 

The external procedures, located in MODULE LOGIN _ PROCEDURES (Example 3-4), must be 
bound with LOGIN__LOGIN (Example 3-3) before the log-in program can be executed. 
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PROGRAM login_login 


• 


J&nolist; 




^include '/sys/ins 


/base. ins. pas'; 


{{include '/sys/ins/pfm. ins. pas' ; 


^include '/sys/ins 


/streams . ins . pas ' ; 


^include '/sys/ins 


/vfmt. ins. pas'; 


^include '/sys/ins 


/error. ins. pas ' ; 


^include '/sys/ins 


/pgm . ins . pas ' ; 


^include '/sys/ins 


/cl. ins. pas'; 


^include '/sys/ins 


/login. ins. pas'; 


Klist; 




CONST 




progjuame = 'login_login' ; 


VAR 




cl_opts 


: cl_$opt_set_t; 


inv_prog 


: string; 


inv_prog_len 


: integer; 


cleaner 


: pfm_$cleanup_rec; 


status 


: status_$t; 


loginjprocedures 


: login_$proc_rec_t; 


stream_in 


: stream_$id_t := stream_$stdin; 


connv 


: pgm_$connv := [stream_$stdin. 




stream_$stdout. 




stream_$errin. 




stream_$errout] ; 


handle 


: pgm_$proc; 


{Login read proced 




lir 6 ' " ' " "- - mill-. . . ii ■■■.■■■■■ii in i- . ii mi -ii -i ■! i J 


< LOGIN_$LOGIN gets 


input via this procedure . } 


FUNCTION my_read( 




IN stream 


stream_$id_t; < Stream ID where user logs in > 


OUT inbuf 


UNIV login_$string_t; { Login string to pass to LOGIN > 


IN inlen 


integer; < Maximum length of string buffer > 


IN pstr 


UNIV login_$string_t; < Prompt string > 


IN plen 


integer; { Length of prompt string > 


IN echo_mode 


boolean; { Indicates whether to echo 




characters on input pad. 




used to prevent password echo > 


IN fillbuf 


UNIV login_$string_t; { Not used, specific to DM } 


IN fillbuflen : 


integer < Not used, specific to DM } 


) : integer; 




EXTERN; 

< Login write proce 




dure '■ '■ " ' -■———■■— .-— _, _ y 


< LOGIN__$LOGIN writ 


es output via this procedure . > 


PROCEDURE my__write( 




IN stream 


stream_$id_t; < Stream ID for user's output > 


IN pstr 


UNIV login_$string_t; i Message to write to output > 


plen 
); 

EXTERN; 


integer < Length of message > 
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{ Login help procedure ■ ■ ■ > 

{ LOGIN_$LOGIN calls this procedure when a user unsucessfully attempts to 

log in. MY_HELP supplies the message by passing the stream ID of the 

help file to LOGIN_$LOGIN . > 



PROCEDURE my_help( 

IN stream : stream_$id_t 

); 

EXTERN; 



< Stream ID on which to write 
help message > 



■C Login open log procedure — > 

•C LOGIN_$LOGIN calls this procedure whenever a user attempts to log in, 
if the LOGIN_$LOG_EVENTS option was set. > 

FUNCTION my_open_log( 

IN log_file 7 UNIV login_$string_t; < Pathname of log file > 

IN log_flen : integer; < Length of "log_file" > 

OUT logstr : stream_$id_t { Returns stream ID of log file > 

) : boolean; < Returns TRUE if successful > 

EXTERN; 



< Exit on error INTERNAL procedure 



===== > 



PROCEDURE err_exit (IN status : UNIV status_$t) ; 

VAR 

stat : status_$t; 

BEGIN 

IF status. all <> status_$ok THEN 
BEGIN 

error_$std_format (status. '%$'); 

pgm_$set_severity(pgm__$error) ; 

pfm_$rls_cleanup (cleaner, stat); -(Reset cleanup handler> 

pgm_$exit; 
END; 
END; < err exit > 



BEGIN i Main 



:=== } 



< Set CL options and initialize the Command Line Handler . > 

cl__opts := [cl_$no_wildcards. cl_$no_keyword_delim] ; 
cl_$init (cl_opts. prog^name. sizeof (prog_name)) ; 
status := pfm_$cleanup (cleaner) ; 

IF status. all <> pfm $cleanup_set THEN 
BEGIN 

pgm_$set_8everity(pgm_$error) ; 

pgm_$exit; 
END; 
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writeln; 
writeln (' 
writeln (' 
writeln (' 
writeln; 
writeln (' 
writeln (' 
writeln C 
writeln; 



This program allows you to log in to a running process *); 
under a different SID. It will invoke a new process using '); 
the /com/sh command. '); 

Before logging you in. LOGIN_$LOGIN prompts for your ppo '); 
and password, and checks the password you supplied against *); 
the password in the registry.'); 



■C Assign values to invoke shell program. > 
inv_prog' := * /com/sh'; 
inv_prog_len := 7; 

■C Get addresses of external I/O procedures for LOGIN_$LOGIN . > 



login_procedures . pread 
loginjprocedures .pwrite 
login_procedures . help 
login_procedures .open_log 



= addr(my__read) ; 
= addr (my_write) ; 
= addr(my_help) ; 
= addr (my_open_log) 



IF NOT login_$login ( stream_in. < 

[login_$log_tvents] . -C 
login_procedures. < 
status ) < 

THEN 
BEGIN 

IF (status. all = login_$err_shut) THEN 
BEGIN 

err_exit (status) ; 
END; 
END; 



Stream ID in which to log in > 
No log events file } 
Address of my login procs > 
Completion status > 



IF status .all : 

BEGIN 

writeln; 
writeln (' 
writeln; 
writeln (' 
writeln; 



status_$ok THEN 

Creating a new shell process: '); 
Type CTRL/Z to terminate program. *); 



pgm_$invoke (inv_prog. 

inv_prog_len. 

0. 0. 

4. 

connv. 

[], 

handle, 

status) ; 



< Invoke program > 

i Number of characters of program > 
{ No arguments > 

< Number of streams > 

■C Pass standard streams > 
■C New process in wait mode > 

< Process handle > 

< Completion status > 



IF status. all <> status_$ok THEN 
err exit (status) ; 



END; 



END. { Main > 



Example 3-3. Performing a Log-In Operation with LOGIN_$LOGIN, Cont. 



Apollo Confidential 



3-7 



Logging In and Changing the Registry 



MODULE login_j>rocedures; 

{ This contains I/O procedures for login. pas. > 



ftnolist; 
^include 
^include 
^include 
^include 
^include 
^include 
^include 
^include 
^include 
^include 
^include 
Blist; 



' /sys/ins/base . ins . pas ' ; 
* /sys/ins/pf m . ins . pas * ; 
Vsys/ins/str earns . ins . pas ' 
' /sys/ins/vf mt . ins . pas ' ; 
Vsys/ins/error . ins . pas * ; 
' /sys/ins/pgm . ins . pas * ; 
' /sys/ins/cl . ins . pas * ; 
' /sys/ins/pad . ins . pas * ; 
* /sys/ins/cal . ins . pas • ; 
' /sys/ins/time . ins . pas * ; 
' /sys/ins/login . ins . pas * ; 



CONST 

newline 
back_sp 
car_ret 
log_name 



VAR 



= chr(10); 

= chr(8) ; 

= chr(13); 

= *login_log_f ile* ; 

stream_in : stream_$id_t := stream_$stdin; 
stream_out : stream_$id_t := stream_$stdout; 
status : status $t; 



i Login read function 



•C This procedure supplies LOGIN_$LOGIN with user input. > 



FUNCTION my_read( 




IN stream 


stream $id t; 


OUT inbuf 


UNIV login_$string_t 


IN inlen 


integer; 


IN pstr 


: UNIV login_$string_t 


IN plen 


• integer; 


IN echo 


: boolean; 


IN fillbuf 


: UNiv login_$string_t 


IN fillbuflen 


: integer 


) : integer; 




VAR 




my_buffer 


: array [1.. 4] of char; 


inptr 


: "string; 


size 


: integer32; 


seek_key 


: stream $sk t; 


i 


: integer; 


status 


: status $t; 



BEGIN < .myjread > 

< Prompt > 

stream_$put_chr (stream_out. addr(pstr). plen. seek_key. status) 
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{ Turn off echo on user's input pad. > 

IF NOT echo THEN 
BEGIN 

pad_$raw (stream_in. status ); < Echo off > 

i := l; 

REPEAT < Get input from user > 

stream_$get_rec(stream_in <( addr(my_buffer) , 1. inptr. 
size. seek_key. status ); 

IF status. all <> status_$ok THEN exit; 

IF inptr" [1] = back_sp THEN 

BEGIN 

IF i > 1 THEN i := i - 1; 
next; 
END; 

inbuf [i] := inptr" [1] ; 
IF (inbuf [i] = car_ret) OR 

(inbuf [i] = newline) THEN exit; 
i := i + 1; 
UNTIL FALSE; 

inbuf [i] := newline; 

my_read := i; < Count includes NEWLINE > 

{ Allow pad to echo input again. } 
pad_$cooked(stream_in. status); 

{ Write a NEWLINE after message. > 

stream_$put_rec(stream_out. addr (newline) . 1. seek_key. status ); 
END -C NOT echo_mode > 
ELSE BEGIN < echojnode > 
< Get input from user } 
stream_$get_rec(stream_in, 

addr (inbuf). 
inlen. 
inptr. 
size. 
seek_key. 
status ) ; 
IF status. all <> THEN 

my_read := 
ELSE my_read := size; 
END; < echojnode > 

return; 

END; i my__read > 
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< Login write procedure 
i Writes output > 



PROCEDURE my_write( 



IN stream 
IN pstr 
IN plen 



stream_$id_t; 

UNIV login_$string_t; 

integer ) ; 



VAR 



status 
seek__key 



status_$t; 
stream $sk t; 



BEGIN 

stream_$put_chr(stream_out. addr(pstr). plen. seek_key. status); 

stream_$put_rec(stream_out, addr(newline) . 1. seek_key. status); 

return; 
END; i my_write > 



{. Login help procedure = t - : ■::?= = ZL^=^i =zz========zz====== .-T--7^ri=. = i 

< This is the message that gets typed when user types h[elp] at the 
Login prompt. > 



PROCEDURE my_help( 
IN stream 



stream $id t) ; 



CONST 

helplinel = ' This is the help message that'; 
helpline2 = ' gets displayed when the user'; 
helpline3 = ' types h[elp] at the prompt.'; 
helplenl = 31; 
helplen2 = 30; 
helplen3 = 28; 



VAR 
status 
seekjcey 



status_$t; 
stream $sk t; 



BEGIN 

my_write( stream_out. helplinel. helplenl); 

my_write( stream_out. helpline2. helplen2) ; 

my_write( stream_out. helpline3. helplen3) ; 
END; i my_help > 



•C Login open log procedure — == > 

-C Open the log file, write the date and time in it. and return the stream ID. > 

FUNCTION my_open_log( 

IN log_file T UNIV login_$string_t; 

IN log_flen : integer; 

OUT logstr : stream_$id_t 
) : boolean ; 

CONST 

my_log_file = , L0GIN_log_f lie • ; 
my_log_flen = 14; 



s" 
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VAR 



td 

da 

mon 

d 

st 



cal_$timedate_rec_t ; 
ARRAY [1. .10] OF Char 
ARRAY [1 . . 10] OF char 
cal_$weekday__t ; 
status $t; 



BEGIN < My_open_log > 

my__open_log := FALSE; 

{ Ignore the log file passed by L0GIN__$L0GIN . and open my own log 
file, return its stream ID to LOGIN_$L0GIN. (If I don't specify 
log_file. L0GIN_$L0GIN writes to 'node_data/siologin_log.) > 

stream_$create(my_log_file.my_log_flen.stream_$append. 
stream_$no__conc_wr ite , logstr . st) ; 
IF st. all <> THEN return; 



< Get decoded local time. > 
cal $decode local time(td); 



i Time stamp > 



WITH td DO BEGIN 

d := cal_$weekday (year, month, day); 



CASE d OF 




< Determine 


day of week. > 


cal_$sun : 


da 


= 'Sunday'; 




cal_$mon : 


da 


= 'Monday'; 




cal_$tue : 


da 


= 'Tuesday'; 




cal_$wed: 


da 


= 'Wednesday'; 




cal_$thu : 


da 


= 'Thursday'; 




cal_$f ri : 


da 


= 'Friday'; 




cal $sat: 


da 


= 'Saturday'; 




OTHERWISE da := 'Doomsday'; 




END; < case day > 




CASE month OF 


< Determine 


month of year. 


1 


mon : = 


' January ' ; 




2 


mon : = 


'February' ; 




3 


mon : = 


'March* ; 




4 


mon : = 


'April' ; 




5 


mon : = 


'May' ; 




6 


mon : = 


' June * ; 




• 7 


mon : = 


•July'; 




8 


mon : = 


'August' ; 




9 


mon : = 


•September'; 




10: mon := 


'October' ; 




1 1 : mon : = 


'November'; 




12: mon := 


'December' ; 




E) 


JD; < case m< 


>nth > 





vfmt_$ws 10 (logstr. 'Xa. Xa Xwd. Xwd Xwd:J{2zwd:?52zwd55. '. 

da. 10. mon. 10. day. year. hour, minute, second. 0) 
END; { WITH td > 
my_open_log := TRUE; 
END; < my_open_log > 
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3.4. Changing User Account Files in the Network Registry 

The LOGIN manager provides a set of LOGIN system calls that allow you to edit user account 
files in the network registry. Network account files associate usernames with log-in passwords 
and home directories. For details on the network registry, see the Administering Your DOMAIN 
System manual. 

When using LOGIN system calls, you must follow a specific order. Figure 3-1 shows the sequence 
of using these calls. 

Program LOGIN System 

System Call 



Initialize LOGIN. 



I 



Set the PPO to user 

whose account file 

you will change. 



I 



Check user password 
(optional) . 



I 



Change user 
password. 



I 



Change user home 
directory. 



Do you 

want to rhangfl ^Yes 

anymore 

users 

? 



LOGIN $OPEN 



LOGIN $SET PPO 



LOGIN $CKPASS 



LOGIN SCHPASS 



LOGIN $CHHDIR 



Sets up storage for 
LOGIN internal datatypes, 
and assigns a LOGIN 
pointer to that storage. 



Converts the PPO string 
to internal form, and 
"remembers" it. 



Checks the registry to see if 
the given password is the 
same as the one listed for the 
current PPO. 



Changes the password of the 
current PPO to the specified 
password.* 



Changes the home directory 
of the current PPO to the 
specified home directory." 



No 



Close LOGIN manager. 



LOGIN $CLOSE 



Updates registry ACCOUNT 
files, and releases storage. 



* Note that changes are not finalized until LOGINJ$CLOSE closes successfully. 
Figure 3-1. Using LOGIN System Calls in Proper Sequence 
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When you initialize the LOGIN manager with LOGIN __$OPEN, it allocates heap storage for its 
private datatypes and returns a pointer value to that storage. Use the LOGIN pointer as an 
input parameter in subsequent LOGIN system calls. 

When you open LOGIN, specify either of two modes: LOGIN_$READ, or LOGIN _$UPDATE. 
LOGIN _$READ allows you to read the user's password but you cannot change it. 
LOGIN_$UPDATE allows you to change a user's account file. Note that to change a user's 
account file, you must be a protected subsystem. 

After initializing the LOGIN manager, set the PPO to the user whose account file you want to 
view or change with LOGIN_$SET__PPO. A user's PPO has four fields: the user's name, 
project name, organization name, and the hexadecimal ID of the user's node. The following are 
two examples of PPO's: WALLY_W.CURRENT.WRITERS.2713, ZACH.NONE.NONE.3541. 

If you do not set the PPO with this call, the LOGIN manager will automatically set the PPO to 
the user who is currently logged in. Even if you want the current user, it's good programming 
practice to set the PPO explicitly with this call. You can specify the current user efficiently by 
specifying a null PPO and a PPO length of zero. LOGIN _$SET_PPO sets the PPO to the 
current user. 

To check a user's password use LOGIN_$CKPASS, specify the LOGIN pointer (returned by 
LOGIN _$OPEN), the password you want to check, and its length. " It returns the error message 
LOGIN _$BAD_PASSWD if the password check failed. 

To change a user's password use LOGIN _$CHP ASS, specifying the LOGIN pointer (returned by 
LOGIN _$OPEN), the new password, and its length. 

To change a user's home directory, use LOGIN __$CHHDIR, specifying the LOGIN pointer 
(returned by LOGIN _$OPEN), the new home directory, and its length. 

Use LOGIN_$CLOSE to close the LOGIN manager. At this time, The LOGIN manager updates 
the account files in the network registry. If a previous LOGIN system call had difficulty with an 
account file, a LOGIN_$CLOSE can fail, which means the registry will not be updated 
accurately. You will have to repeat the entire LOGIN sequence since you opened LOGIN with 
LOGIN_$LOGIN. Use LOGIN_$CLOSE even if LOGIN_$OPEN failed, because when 
LOGIN_$OPEN fails it can leave LOGIN partially opened. 



3.4.1. Sample Program — Changing the Registry ACCOUNT Files 

Example 3-5 shows how to use the various LOGIN system calls to check and change a password 
and to change a home directory. 
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PROGRAM logln_change_pass_dir; 

SSnolist; 

SSinclude ' /sys/ins/base . ins . pas ' ; 

JSinclude * /sys/ins/vf mt . ins . pas * ; 

^include ' /sys/ins/error . ins . pas ' ; 

% include '/sys/ins/pgm. ins. pas' ; 

^include '/sys/ins/cl. ins. pas'; 

^include ' /sys/ins/login . ins . pas * ; 
Hlist; 

CONST 

prog_name = *LOGIN_chng_pass_dir*; 



VAR 

command 

command_len 

ok 

null_line 

ppo 

ppo_len 

verify 

num_args 

login_ptr 

badjmame 

bad_pname_len 

errout 

err_status 

status 



string; 

integer; 

boolean; 

boolean; 

string; 

integer; 

boolean; 

integer; 

login_$ptr; 

name_$pname_t ; 

integer; 

stream_$id_t := stream_$errout; 

status_$t; 

status $t; 



{ ***************************************************************** > 



PROCEDURE check_err ( IN status 

IN msg 



: status_$t; 

: UNIV string ); 



BEGIN 

IF (status. code = ) THEN 
RETURN; 

error_$std_format (status, msg ); 

pgm_$set_severity (pgm_$error ); 

pgm_$exit 
END; < check_err > 

{ ***************************************************************** > 
PROCEDURE chnjpass; < Go here if user specified chpass > 

-C If the user specifies the -v[erify] option with a password, this 
procedure checks the specified password; otherwise, it changes the 
user's password to the specified password. > 



VAR 



old_pass : string; 

new__pass : string; 

opass_len : integer; 

npass__len : Integer; 
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BEGIN < chn_pass > 

< Get password. If user wants to verify current password, the next argument 
is the password to check. If the user wants to change the password, 

the next argument is the new password. > 

IF verify THEN 

ok := cl_$get_arg (cl_$next. old_pass. opass_len. sizeof (old_pass)) 
ELSE 

ok := cl_$get_arg (cl_$next. new_pass. npass_len. sizeof (new_pass)) ; 
cl_$check_unclaimed; 

< If verifying old password, open LOGIN for read access, since you are 
not changing the registry. > 

IF verify THEN 
BEGIN 

login_$open (login_$read. < Open LOGIN manager for updates > 
login_ptr, { Pointer to LOGIN datatypes > 
status) ; { Completion status > 
check_err (status, * Cannot perform LOGIN open. 58$'); 



< Pointer to LOGIN datatypes > 

< PPO file specified by user > 
{ Length of PPO file > 

{ Completion status > 
r); 



< Set the PPO to operate on. > 

login_$set_ppo ( login_ptr. 

PPO. 

ppo_len. 
status ) ; 
check_err (status. ' Cannot set user''s PPO 
< Check old password. > 

login_$ckpass (login_ptr. { Pointer to LOGIN datatypes > 
old_pass, i Old password > 
opass_len, { Length of old password > 
status) ; < Completion status > 

IF status. all = login_$bad_passwd THEN BEGIN 

vfmt_$ws2(errout. 'Old password is incorrect.??.', 0. 0) ; 
pgm_$set_se verity (pgm_$f alse) ; 
pgm_$exit; 
END 
ELSE vfmt_$write2(' Password verified. %. ' . 0. 0); 
END 
ELSE BEGIN < Change current password to specified password. > 

login_$open ( login_$update. login_ptr. status); 
check_err (status. * Cannot perform LOGIN open. %$'); 



■C Set the PPO to operate on. > 

login__$set_ppo ( login_ptr. 

PPO. 
ppo_len, 

status ) ; 



-C Pointer to LOGIN datatypes > 
< PPO file specified by user > 
{ Length of PPO file > 
{ Completion status > 



check_err (status, ' Cannot set user''s PPO. 55$'); 

login_$chpass ( login_ptr, < Pointer to LOGIN datatypes > 
new_pa8s. {. New password > 

npass_len. {. Length of new password > 

status ) ; < Completion status > 
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IF status. all <> status_$ok THEN 
BEGIN 

login_$err_context ( login_ptr. 

err status . 



vfmt $vs2 (errout. 



< Pointer to LOGIN datatypes > 
-C Returns error status > 
bad_pname, -C Pathname of user that failed > 
bad_pname_len. { Length of bad pathname > 
status ) ; { Completion status > 
Cannot change password for: '. 



bad_pname, sizeof (bad_pname) ); 



END; 



END; 



login_$close ( login_ptr. status ) ; 

check_err (status . ' Cannot perform LOGIN close. %$'); 
END; < chn_pass > 

PROCEDURE chn dir; {. ************************************************ > 

•C This procedure changes the user's home directory listed in 
the user's ACCOUNT file to the specified home directory. } 



VAR 



new_dir 
dir len 



string; 
integer; 



BEGIN -C chn_dir > 

{ Get the new home directory. > 

ok := cl__$get_arg (cl__$next. new_dir. dir_len. sizeof (new_dir)) ; 
cl_$check_unclaimed; 

login_$open (login_$update. {. Open LOGIN manager for updates > 
login_ptr. < Pointer to LOGIN datatypes > 
status) ; { Completion status } 

check_err (status. * Cannot perform LOGIN open. 55$'); 

< Set the PPO to operate on. > 

login_$set ppo ( login ptr. < Pointer to LOGIN internal data } 
ppo. " < PPO > 
ppo_len. < Length of PPO > 
status ) ; < Completion status > 
check_err (status, * Cannot set user"s PPO. %$') ; 
login_$chhdir ( login_ptr. < Pointer to LOGIN internal data > 
new_dir. < Name of new home directory > 
dir_len. < Length of new home directory > 
status) ; { Completion status > 
IF status. all <> status_$ok THEN 
BEGIN 

login_$err_context ( login_ptr, { Pointer to LOGIN datatypes > 

err_status. < Returns error status > 
bad_pname. < Pathname of user that failed > 
bad_pname_len. { Length of bad pathname } 
status ) ; < Completion status > 
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vfmt_$ws2 (errout. • Cannot Home directory for: *. 
bad_pname. sizeof (bad pname) ); 
END; 

login_$close ( login_ptr, status ) ; 

check_err (status, ' Cannot perform LOGIN close. %$'); 

END; < chn_dir > 

■{ ****^****^**^******^************#***************«*^******«******* > 
BEGIN { Main > 

< Initialize the CL. but don't parse the command line. > 

cl_$setup ( [] . < Default CL options in effect > 

prog_name. < Name of program > 

sizeof (prog_name)) ; < Length of program name > 

< Get the line to parse from standard input. > 

writeln; 

writeln ( ' ***** *); 

writeln; 

writeln ( ' This program allows you to change a user''s '); 

writeln ( ' password or home directory. '); 

writeln; 

REPEAT < until user types CTRL/Q > 

writeln; 

writeln ( ' Enter the user'*s PPO whose password or home '); 

writeln ( ' directory you want to change.*); 

writeln; 

< Get the PPO. > 

ok := cl_$parse_input ( stream_$stdin, null_line ); 
ok:= cl_$get_arg (cl_$first. ppo. ppo_len. sizeof (ppo)) ; 



writeln; 
writeln ( 
writeln ( 
writeln; 
writeln ( 
writeln ( 
writeln; 
writeln ( 
writeln ( 



Type "chpass -v[erify] ''password * ' " if you want to check') 
the current password.'); 

Type "chpass ''password'* " to change the current password'); 
to the specified password.'); 

Type "chhdir '*dir*' " to change current home directory'); 
to the specified home directory.'); 
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< Get the operation. > 

ok := cl_$parse_input ( stream_$stdin. null__line ); 

•C Check if user supplied the verify option on the command line. 
Check for any invalid keywords; exit if user specified any. > 

verify := cl_$get_flag C-v[erify] '. num_args) ; 

cl_$ che ck_uncl aimed; 

{ Get the operations. > 

IF cl_$get_arg (cl_$first. command. command_len. sizeof (command)) THEN 
BEGIN 

IF cl_$match C'chpass[]*, command, command_len) THEN 

chn_pass; 
IF cl__$match CchhdirC]'. command. command_len) THEN 

chn_dir; 

END; 
UNTIL FALSE; < User types CTRL/Q > 
END. < Main > 
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Chapter 4 
More Process Manager System Calls 



This chapter describes DOMAIN system calls for managing programs. These calls allow you to 

• Load and call a program or library object n odule. 

• Assign a name given its process UID. 

• Set the priority given its process UID. 

These system calls are part of the DOMAIN subsystems for managing programs. For details on 
other calls in these subsystems, see the chapter on managing programs in the Programming with 
General System Calls manual. 

4.1. System Calls, Insert Files, and Data Types 

To load and call object modules or libraries, use the LOADER manager. These calls are located 
in the LOADER insert file. Note that they have the PM prefix. 

To assign a name to a given process UID, use PM__$SET_NAME, which is in the PM insert file. 

To set the priority of a given process UID, use PROC2__$SET_PRIORITY, which is in the 
PROC2 insert file. 

When using these system calls in your program, you must specify the appropriate insert file for 
the language your are using. Where prefix is the desired subsystem, the insert files are 

/SYS/INS/prefix.INS.C for C. 

/SYS/INS/prefix.INS.FTN for FORTRAN. 

/SYS/INS/prefix.INS.PAS for Pascal. 

For details on the system call syntax, data types, and error messages, Part II of this manual. For 
details on other system calls in these subsystems, see the DOMAIN System Call Reference 
manual. 



4.2. Loading and Calling a Program with LOADER System Calls 

The two system calls in the LOADER manager allow you to load a program or library object 
module into memory so that it can be executed. PM__$LOAD converts a specified object module 
and returns its starting address. PM_$CALL invokes the loaded object module. 

These calls work similarly to PGM_$EMVOKE, except that PGM__$INVOKE performs some 
operations automatically. Table 4-1 highlights the differences between PGM__$INVOKE and the 
LOADER calls. The resources referred to in this table include read/write storage, mark release 
handlers, address space, and stream descriptors. 

For details on using PGM_$INVOKE, see the Programming with General System Calls 
manual. 
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Table 4-1. Difference Between LOADER and PGM_$INVOKE System Calls 



Condition 


A Loads & Calls B (PM) 


A Invokes B (PGM) 


Program Level: 

Resources that B 

acquires : 

Storage unmapped : 


Not created. 

Released when 
A terminates.* 

When A terminates. 


Created. 

Released when 
B terminates. 

When B terminates. 


* Note that if A continues to load programs that terminate abnormally, 
you can run out of resources (such as stream descriptors or address 
space) since they don't get released until A terminates. 



PM_$LOAD and PM_$CALL are most commonly used to load libraries. You would also use 
them when you want to control how the object module gets loaded. For example, you can have 
PM_$LOAD make a writable copy of .he object module so that you can set breakpoints without 
changing the original object module. Or you can have PM_$LOAD report an error if the object 
module contains any unresolved global variables. 

When you use PM___$LOAD, you control how the object module gets loaded by setting the 
options of a variable in PM__$LOADER_OPTS format. Table 4-2 lists the options you can 
specify. 

Table 4-2. PM_$LOAD Options 



PM_$LOAD Option 


Description 


PM_$COPY_PROC 

PM_$INSTALL 

PM_ $INSTALL _ SECTIONS 

PM_ $LOAD _ WRITABLE 
PM_$NO_UNRESOLVEDS 


Copies the object module into read/write storage 
so that you can write to the object module without 
changing the original object module. If you do not 
specify this option, PM_$LOAD maps the object 
module directly. 

Indicates that you are loading a library. 
PM__$LOAD makes all the global entry points, 
which were marked at binding, available to other 
programs. Specify this option when loading libraries. 

Indicates that you are loading a library 
containing global sections. PM_$LOAD makes these 
global sections, which were marked at binding, 
available to all programs. Specify this option 
when loading libraries. 

Allows you to write to the object module. 
Specify this option when you want to write to the 
object module without making a copy of it first. 
The debugger provides this with its -NC option. 

Returns an error message if the object module 
contains any unresolved global variables. 
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After you load the program with PM_ $LOAD, use PM_$CALL to invoke it. When using 
PM_$CALL, you give it a pointer to the routine you want to call. This is the start address of 
the object module returned by PM_$LOAD, which is the first field in the predefined record, 
PM_$LOAD_INFO. 

Section 4.2.1 is a sample program using PM_$LOAD and PM_$CALL to load and invoke a 
program. 

Even though PM__$CALL is a function, you usually load a procedure, so the value it returns is 
meaningless. However, you can use PM_$CALL to return a value from the object module; 
PM_$CALL will pass a 32-bit integer value along to the main program as its return value. Note 
that you cannot pass any arguments to the routine you are invoking. 

You can have PM_$CALL return data types other than a 32-bit integer, so long as the data fits 
in 32 bits or fewer. To do so, create a variant record with a 32-bit integer as one variant, and 
the actual data type returned by the target routine as another variant. Pad the second variant 
out to 32 bits. Assign the 32-bit integer value from PM_$CALL to the 32-bit integer variant, 
and take your desired data from the other variant. Example 4-1 shows how you would use 
PM $CALL with a variant record. 



< This Pascal example uses PM_$CALL to call a function that returns a 
16-bit integer data item: } 

VAR 



< Filler > 

•C Desired data > 



ret: RECORD CASE INTEGER OF 

1 : (long : integer32) ; 
2: (pad : Integer; 
wanted_I : Integer) ; 
END; 

load_info : pm_$load_info; 

BEGIN 

{. Load my_integerl6_f unction. > 



{ Call my_integerl6_function using the start address returned by 
the PM_$LOAD_INFO data type in PM_$LOAD . } 

ret. long := pm_$call(load_info.start_addr) ; 

•(Write out the returned value as a 16-bit integer . > 

writeln (ret. wanted I); 
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4.2.1. Sample Programs Using LOADER System Calls 

Example 4-2 is a sample program that loads and calls a second program 
(PM_LOAD_THIS.BIN) using PM_$LOAD and PM_$CALL. It gets the load options from 
the command line. 



PROGRAM pm_load; 




%nolist; 




^include Vsys/ins/base .ins. pas' ; 




^include * /sys/ins/s treams . ins . pas ' ; 




^include ' /sys/ins/cl . ins . pas ' ; 




^include ' /sys/ins/loader . ins . pas ' ; 




^include Vsys/ins/vf mt . ins . pas • ; 




JJinclude ' /sys/ins/pgm. ins. pas' ; 




^include * /sys/ins/error . ins . pas ' ; 




S5list; 




CONST 




prog_name = *pm_load'; 




prog_to_load = 'pm_load_this.bin'; 




VAR 




name : n&me_$pname_t ; 




len : integer; 




num_args : integer; 




load_opts : pm_$loader_opts; 




sec_info : pm_$load_info; 




status : status_$t; 




pm_status : status_$t; 




ok : boolean; 




null_line : boolean; 




junk : integer32; 

r , ■ 




PROCEDURE check_status; 


— — — — — — ___ y 


BEGIN 




IF status. all <> status_$ok THEN 




BEGIN 




error_$print (status) ; 




pgm_$exit; 




END; 




END; -C check_status > 

x — — 


\ 


\ 


«r 
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BEGIN < Main > 

cl_$setup ( [] . < Default CL options in effect > 

prog_name. < Name of program > 
sizeof (prog_name)) ; < Length of program name > 

{Initialize empty set of loader options. > 
load_opts : = [] ; 



writeln ( 

writeln; 
writeln ( 
writeln; 
writeln ( 
writeln ( 
writeln ( 
writeln ( 
writeln ( 
writeln; 



This program loads the object module, *, 
prog_name : sizeof (prog_name) ); 

You can specify the following options : * ) ; 

-c[copy] to copy the object module so you can write to it, 
-w[rite] to make the original object module writable. '); 
-nr [esolveds] to terminate program with an error if *); 

global variables are unresolved. '); 
-lib[rary] to load a library. '); 



') 



ok := cl_$parse_input ( stream_$stdin. null_line ); 

< Get keywords, then check for any invalid keywords; 
exit if user specified any. > 

IF cl_$get_flag C*-c[opy]', num_args) 

THEN load_opts := [pm_$copy_proc] ; 
IF cl_$get_flag C-w[write] '. num_args) 

THEN load__opts := [pm_$load_writable] ; 
IF cl_$get_flag ('-nr [esolveds] *, num_args) 

THEN load_opts := [pm_$no_unresolveds] ; 
IF cl_$get_flag C-lib[rary] * . num_args) 

THEN load_opts := [pm_$install + pm_$install_sections] 



cl_$check_unclaimed ; 

pm_$load ( prog_to_load. < 
sizeof (prog_to_load) . i 

load opts, -C 

0. " i 

sec_info, -C 

status) ; i 

check status; 



Name of program to load > 

Length of program } 

Load options > 

Get start address only > 

Returns star', address of object module } 

Completion status > 



IF status. all = status_$ok THEN 
BEGIN 

writeln; 

writeln ('Program loaded sucessfully . ') ; 

Junk := pm_$call( sec_inf o . start_addr) ; 
END; 
END. { pm_load > 
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4.3. Setting a Process Priority 

The process priority is an integer ranging from 1 (low) to 16 (high). When the operating 
system decides which process to run next, it chooses the process that currently has the highest 
priority. 

The priority changes while a process executes. Its priority increases as the process waits for 
events, and decreases as it computes for long periods without waiting. To find out the priority 
range of a running process, use the PST (process _ status) Shell comand. 

By default, a process will have a priority range of 3 to 14. You can change this range by 
specifying different high and low values in the PROC2_$SET_ PRIORITY system call. These 
values must be between of 1 to 16. The PPRI (process _ priority) Shell command uses the 
PROC2__$SET_PRIORITY system call. 

Note that the Display Manager (DM) process has a priority range of 16, 16. See Section 4.5 for 
an example of PR0C2__$SET_ PRIORITY in a program. 



4.4. Assigning a Name to a Process 

When the operating system creates a process, it assigns a number or unique identifier (UID) to 
the process. You might want to refer to the process by name rather than number so that you can 
identify it more easily. You do so with the PM__$SET_NAME system call. You supply the 
name, its length, and process UID; the call returns a completion status. 

After assigning a name to a process with PM__$SET__NAME, Shell commands, such as PPRI 
(process _ priority), PST (process_ status), and SIGP (signal _ process) refer to the process by its 
name. 

Server programs such as " alarm _ server" or ■mail" use PM_$SET_NAME to name their 
server processes. Users can name a process they create by using the -N option with the Shell 
command CRP (create _a_ process), and the DM commands, CP (create _ process), CPO 
(create __ process _ only) j and CPS (create_process__server). 

NOTE: A process can be assigned a name only once . You cannot 
rename or remove a name once it is assigned. 

If you try to name a process that already has a name, you will get the error, 
PM $ALREADY NAMED. 



4.5. Sample Programs Using PM, PROC2 System Calls 

Example 4-3 is a sample program using PM_$SET_NAME to assign a name to a process, and 
PROC2__$SET__PRIORITY to change its priority. The program first creates an unnamed 
process using PGM__$INVOKE, and then sets the name. Before it sets the name, it must first 
get its process UID using the PGM_$GET_PUE> system call. 
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PROGRAM pm_proc2_set_name_priority; 



SSnolistj 
^include 
^include 
^include 
^include 
^include 
^include 
Xlist; 



* /sys/ins/base . ins . pas * ; 
' /sys/ins/proc2 . ins . pas * ; 
' /sys/ins/pm . ins . pas ' ; 
*/sys/ins/streams.ins .pas 
' /sys/ins/error . ins . pas ' ; 
* /sy s/ins/pgm . ins . pas * ; 



CONST 

lo_bound =9; 
hi bound = 5; 



< Low bound of process priority range > 
{ High bound of process priority range > 



VAR 

uid 

status 

connv 

handle 

prog_name 



uid_$t; 
status_$t; 
pgm_$connv; 
pgm_$proc; 
name $name t 



i Process UID > 

< Connection vector 

< Process handle } 

= 'invoke clock'; { 



PROCEDURE check status; < 



Name to give process > 



BEGIN 

IF status. all <> status_$ok THEN 
BEGIN 

error_$print (status) ; 
pgm_$exit; 
END; 
END; { check status } 



BEGIN -C Main 



=== } 



writeln; 
writeln ( 
writeln ( 
writeln ( 
writeln ( 
writeln; 



This program invokes a process to run a digital clock. ') 

names the process. INVOKE_CLOCK . and sets its priority. ') 

You can see the process listed by name by invoking the ') 
Shell command PST (process_status) . '); 



< Load the standard streams to pass to the invoking program. > 



connv [0] 
connv [1] 
connv [2] 
connv [3] 



= stream_$stdin; 
= stream_$stdout; 
= stream_$errin; 
= stream $errout; 



{Create an unnamed child process using PGM_$ INVOKE . > 
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pgm_$invoke ( 


•digclk.bin*. 


{ Pathname of program to invoke > 




10. 


{ Length of pathname > 




0. 


{ Number of arguments. to pass > 




0. 


< Argument vector > 




4. 


{ Number of streams to pass > 




connv. 


i Array of stream IDs to pass > 




[]. 


•C Invoke program > 




handle. 


< Returns process handle for UID > 




status ) ; 


< Completion status > 


check_status; 






{ Get the UID of 


the child process. > 


pgm_$get_puid 


( handle. 


{ Process handle > 




uid. 


< Returns UID > 




status ) ; 


{ Completion status > 


check_status; 






{ Set name of the 


child process. 


> 


pm_$set_name 


( prog_name. 


{ Name to give process > 




sizeof (progjaame) . < Length of name > 




uid. 


i UID of the process } 




status ) ; 


{ Completion status > 


check_status; 






writeln; 






writeln (' The name of this 


process is : * . 


prog_name : sizeof (prog_name) ); 


{ Change the priority of the child process. > 


proc2_$set_priority ( uid. 


< UID of current process > 




lo_bound. < Low bound of priority range > 




hi_bound. < High bound of priority range > 




statue 


; ) ; { Completion status > 


check_status; 






writeln j 






writeln The new priority 


is: '. lo_bound. hi_bound ) ; 


END. 
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Chapter 5 
Handling Dynamic Storage 



The DOMAIN system contains two managers that allocate dynamic storage. The Read/Write 
Storage Manager (RWS) is a set of DOMAIN system routines that allocates dynamic storage. 
These system calls allow you to request a specific amount of storage during the execution of your 
program. Each call returns a pointer to the address of the new storage space. 

The Basic Allocate/Free Heap Manager (BAF) allows you to create a heap and perform allocate 
and free operations on that heap. You would use the BAF manager when you want to specify 
where the storage comes from, or have a stricter control over allocating and releasing storage. 

We describe both the RWS and BAF managers in this chapter. 



5.1. System Calls, Insert Files, and Data Types 

To use the RWS manager, use the system calls with the prefix RWS. To use the BAF manager, 
use the system calls with the prefix BAF. This chapter describes how most of these calls work. 
For details on system call syntax, data types, and error messages, see Part II of this manual. See 
also the DOMAIN System Call Reference manual for details on previously released RWS calls. 

When using RWS or BAF system calls in your program, you must specify the appropriate insert 
file for the language your are using. Where prefix is the desired subsystem (RWS for read/write 
storage, BAF for basic allocate/free heap storage), the insert files are RWS insert files are 



/SYS/INS/prefix.INS.C 
/SYS/INS/prefix.INS.FTN 
/SYS/INS/prefix RWS.INS.PAS 



forC. 

for FORTRAN. 

for Pascal. 



5.2. Overview of the RWS System Calls 

RWS system calls provide a few different ways to allocate storage. Which method you should use 
depends on 

• How long you want to keep the storage. 

• How much system overhead you can afford. 

• How you want to the storage to be accessed, for example, within the calling process or 
among all processes. 

Table 5-1 lists the RWS system calls you can use to allocate storage dynamically. Details on each 
type of storage follow. 
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Table 5-l A . RWS System Calls to Allocate Dynamic Storage 



System Call 


Description 


RWS_$ALLOC 


Allocates read/write storage for FORTRAN 
or Pascal programs. 


RWS_$ALLOC_HEAP 


Allocates heap* (releasable read/write) 
storage for programs. 


RWS_$ALLOC_HEAP_POOL 


Allocates heap* (releasable read/write) 
storage in a specified pool. 


RWS_$ALLOC_RW 


Allocates read/write storage for 
Pascal programs only. 


RWS_$ALLOC_RW_POOL 


Allocates read/write storage in a 
specified pool. 


RWS_ $RELEASE_HEAP 


Releases the storage you allocated with 
RWS $ALLOC HEAP or 
RWS_$ALLOC_HEAP_POOL. 


* When these calls allocate read/write storage, they provide you with 
pointers to storage that can be released when you no longer need it. 
To distinguish this from unreleasable read/write storage, we refer to 
this as heap storage. Note that this differs from a BAF heap described 
in Section 5.3. 



You can use all the above systems calls in Pascal and C programs. However, in C programs, you 
might want to use the C Library routine, MALLOC. Note that due to FORTRAN calling 
conventions, the only RWS call you can use in FORTRAN programs is RWS_$ALLOC. This 
limitation will be corrected in a future AEGIS Software Release. 

Whether you allocate read/write storage or heap storage depends on how long you want to keep 
the storage. Once you allocate read/write storage, the storage exists until the program 
terminates. However, you can explicitly release heap storage once you have finished using it. 

The heap requires more system overhead initially. Currently, an allocation from the RWS heap 
requires between 4 to 16 bytes of overhead — to keep track of the allocated storage. Note that 
the amount of overhead is subject to change, so your program should not depend on an exact 
amount of system overhead. The system requires no overhead to allocate read/write storage. 

You usually want to allocate heap storage during your program if you need a substantial amount 
of storage for a limited period of time, or if you want to keep your working set as small as 
possible. 

For example, the CL allocates heap storage to hold the tokens while parsing the command line. 
It frees the storage after parsing the line. The CL uses heap storage because it can tell when it no 
longer needs the storage. Also, if it doesn't free the storage, it would eventually run out. 

You would allocate read/write storage if the amount of overhead for a heap is unacceptable, or if 
you do not need to release the storage before terminating the program. 
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If you want to control how the dynamic storage can be accessed, specify the appropriate option in 
the RWS_$POOL system calls. You can allocate both read/write storage and heap storage in 
these pools so that you can 



Limit storage to local access within the calling process, 
option (RWS_$STD_POOL) in most cases. 



Specify the standard pool 



• Make storage accessible to all processe.. Specify the global pool option 
(RWS_$GLOBAL_POOL) to share information among processes. For example, you 
might want to implement a global queue to pass messages between processes. Note 
that pointers are valid in all processes because all processes have a reserved identical 
portion of address space. 

• Make storage accessible to the calling process and to an overlay process. Specify the 
stream pool option (RWS_$STREAM_TM__POOL) when your program needs to 
pass information to a program invoked with a UNIX EXEC system call. For example, 
the STREAM manager uses RWS_$STREAM_TM_POOL to pass an open stream 
to a program invoked with an EXEC call. It stores information about that stream in 
the stream pool. 

Table 5-2 summarizes the aspects of each type of storage allocation. 

Table 5-2. Summary of Types of Storage Allocation 





Read/Write Storage 


Heap Storage 


Standard 


Storage kept until program 


Storage kept until you 


Pool 


exits or until it invokes 
a program with a UNIX 
EXEC system call . 


release it with 
RWS_$RELEASE_HEAP . the 
program exits, or the 
program invokes a program 
with a UNIX EXEC call. 




No system overhead. 


About 16 bytes of 
system overhead. 




Storage available to 


local process only. 


Global 


Storage kept until reboot. 


Storage kept until 


Pool 




you release it with 
RWS_$RELEASE_HEAP or reboot. 




About 4 bytes of system 
overhead. 


About 4 bytes of system 
overhead. 




Storage available to 


all processes . 
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Table 5-2. Summary of Types of Storage Allocation, Cont. 





Read/Write Storage 






Heap Storage 


Stream 


Storage kept until 






Storage kept until 


Pool 


program exits. 
No system overhead. 






you release it with 
RWS_$RELEASE_HEAP . 

About 16 bytes of 
system overhead. 




Storage available to 
program invoked vith 


the local process or to a 
a UNIX EXEC system call . 



NOTE: Do not depend on the exact amount of system overhead 
used in RWS system calls . The amount of overhead is 
subject to change. 



5.3. Overview of the BAF System Calls 

The basic allocate/free (BAF) heap manager allows you to create a heap to handle dynamic 
storage allocation yourself. The advantage to handling storage with the BAF manger is that you 
can specify from where BAF gets the storage. You also have tighter control over allocating and 
freeing the storage you use. 

For example, you could allocate storage with BAF system calls to control the size of your working 
set by subdividing your heap into smaller heaps. Place storage referenced closer in time in the 
same heap. 

To use the BAF manager, you follow this sequence: 

1. Create a heap with BAF_$CREATE. 

2. Allocate storage from the heap with BAF_$ALLOC. 

3. Release the storage and return it to the heap with BAF_$FREE when your program 
is through using the storage. 

4. Add storage space to the heap, if necessary, with BAF __$ADD_ SPACE. 

When creating the heap, you can specify the storage space in many ways, for example, declaring 
an array in a program, using an RWS_$ALLOC_RW or MS_$CRMAPL system call. 

If the storage is shared, you must specify the BAF_$SHARED option in the first parameter of 
BAF__$CREATE. By setting the BAF__$SHARED option, subsequent calls to BAF_$ALLOC 
and BAF_$FREE will obtain locks before performing their operation. This is necessary to 
prevent two processes from corrupting the heap by using it at the same time. 
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Once you have created the heap, you can perform any number of allocate and free operations. 
Use BAF_$ALLOC to allocate storage from the heap. BAF__$ALLOC allocates a contiguous 
region of storage up to a maximum of 32K bytes. If you require more storage, you can make 
subsequent calls to BAF_$ALLOC. 

BAF_$ALLOC could fail if there's not enough storage space left in the heap (it returns the error 
BAF_$NO__ROOM). You can add space to the heap with BAF_$ADD_ SPACE. 

BAF_$ALLOC and BAF__$FREE could fail if the heap overwrites the overhead information 
(pointers, size) which is located before each block. This can occur if your program refers to an 
array beyonds its bounds. 



5.3.1. Improving Performance Under Current Implementation 

This section describes some characteristics of the BAF manager that might help you improve 
performance. We reserve the right, however, to change details of this implementation in the 
future to improve efficiency. 

The following implemenation details might help you use a BAF heap more efficiently: 

• The current implementation of BAF manager uses a single tag before the block of 
storage to keep track of the block. 

• BAF_$ALLOC combines adjacent free items while searching for the free list for a 
large enough block to perform the allocate operation. 

• When you free items, BAF__$FREE puts the free blocks on a free list. Therefore, 
freeing is very efficient. 

• Allocating and freeing blocks of the same size is very fast. 

• The BAF manager tends to reuse recently freed blocks, so you get desirable working 
set behavior. 



5.4. Sample Program Using RWS and BAF System Calls 

The program in Example 5-1 shows how to use BAF system calls to allocate storage. It uses the 
MS_$CRMPL system call to create a temporary file to store the heap. (You might want to use a 
file to maintain storage at different program levels in a single process.) The program then 
performs allocates and frees from the file using BAF system calls. 
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PROGRAM manage_mapl_heap; 

^include '/sys/ins/base. Ins. pas'; 

^include '/sys/ins/baf. ins. pas' ; 

^include '/sys/ins/cl. ins. pas'; 

^include ' /sy s/ins/pgm . Ins . pas 

^include '/sys/ins/nrs. ins. pas'; 

^include '/sys/ins/error. ins. pas' 

^include '/sys/ins/vfmt. ins. pas', 

95include '/sys/ins/ms. ins. pas'; 

CONST 

heap_chunk_size = 32 * 1024; 
TYPE 

stack_pointer = ~stack_item; 
stack_item = RECORD 
stack_data : string; 
next_link : stack_pointer; 
END; < record > 



VAR 
stack 
amount 
command 
command_len 
name 

new_name 
name_len 
address 
old_top 
null_line 
stack_ptr 
stack_address 
status 
ok 



univ_ptr; 

integer; 

string; 

integer; 

string; 

string; 

integer; 

stack_pointer 

stack_pointer. 

boolean; 

stack_pointer 

baf_$t; 

status_$t; 

boolean; 



:= NIL; 



;= NIL; 



< Exit on error procedure = 



PROCEDURE check_status (IN status : UNIV status_$t) 

BEGIN 

IF status. all <> status_$ok THEN 
BEGIN 

error_$std_format (status. '%$') ; 

pgm_$set_severity(pgm_$error) ; 

pgm_$exit; 
END; 
END; { err exit > 
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< Allocate storage for new top of stack 



PROCEDURE add_storage ( IN new_name : string; 

IN OUT top : stack_pointer ) ; 
VAR 

temp_ptr : stack_pointer; 

BEGIN < add_storage > 

< Allocate enough storage for the new name . > 
temp_ptr := BAF_$ALLOC (stack_address. 



check status (status) ; 



■C Address of heap from 
which to get storage > 
sizeof (stack_item) . < Size of storage to allocate > 
status ) ; < Completion status > 



IF temp_ptr = NIL THEN 
BEGIN 

•C Create another temporary file to get more storage . > 

stack := MS_$CRMAPL ( ' *. < Object to be mapped > 

0. -C Length of object > 

0. {. First byte to be mapped > 

heap_chunk_size. { Number of bytes to map > 

ms_$nr_xor_lw. < Allow 1 writer, any readers > 

status ) ; i Completion status > 

check_status (status) ; 

BAF_$ADD_SPACE ( stack_address, < Address of heap to which to add 

storage > 
stack, { Address of added storage > 

heap_chunk_size, < Amount of storage to add > 
status ); < Completion status > 

check_status (status) ; 

temp_ptr := BAF_$ALL0C (stack_address, < Address of heap from which 

to get storage > 
sizeof (stack_item) .< Size of storage to allocate} 
status ) ; { Completion status > 
check_status (status) ; 
END; 

temp_ptr~ . stack_data := new_name; ■( Link new name } 

temp ptr~.next_link := top; { Connect to previous top > 

top := temp_ptr; < Redefine top of stack > 

END; < add_storage > 
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< Check for empty stack 



FUNCTION empty_stack (IN top : stack_pointer) : boolean; 
BEGIN < empty_stack > 

empty_stack := top = NIL 
END; < empty_stack > 
•C Pop name off stack and free storage ' '"■ "'■ =i:-r. :■-■■■ ;■ = 



PROCEDURE free_storage ( OUT del_name : string; 

IN OUT top : stack_pointer ) ; 
BEGIN i free_storage > 

IF empty_stack(top) THEN 

writeln (* Cannot remove name from empty list. ') 

ELSE BEGIN 

del_name := top~.stack_data; {. Get name to delete > 

old_top := top; < Save old top of stack > 

top := top"\next_link; < Make next name top of stack > 

baf_$free ( stack_address. < Address of storage from which to free 

block > 
old_top. < Address of block of storage to be freed > 
status ) ; < Completion status > 
check_status (status) ; 
END; 
END; < free_storage > 

BEGIN i Main > 

< Allocate file to hold stack info then create a heap to handle the stack. 
MS_$CRMAPL creates a temporary file and points to the first byte. > 

stack := MS_$CRMAPL ( ' '. { Object to be mapped > 

0, < Length of object > 

0. < First byte to be mapped > 

heap_chunk_size. < Number of bytes to map > 

ms_$nr_xor_lw. < Allow 1 writer, any readers > 

status ) ; { Completion status > 

check_status (status) ; 

IF stack <> NIL THEN 
BEGIN 

stack_address := BAF_$CREATE ( [] , i No options > 

stack. { Address of storage to use } 

heap_chunk_size, < Maximum size of stack > 
status ) ; i Completion status } 

che ck_status (status) ; 
END; 
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{ Get the line to parse from standard input. > 

writeln; 

writeln ( 'This program allows you to add or free storage from the heap. ') 

writeln; 

REPEAT < user types CTRL/Q } 

writeln ( 'Type "ADD name" to the top of the list. '); 
writeln ( 'Type "FREE name" from the top of the list.'); 
writeln ( 'Type "Q[uit]" to quit. '); 

< Parse the input. > 

ok := cl_$parse_input ( stream_$stdin. 

null_line ) ; 

IF null_line THEN 
BEGIN 

writeln ('No input. Terminating program.'); 

pgm_$exit; 
END; 

< Get keywords, then check for any invalid keywords; 
exit if user specified any. > 

IF cl_$get_arg (cl_$first. command. command_len. sizeof (command)) THEN 

begin" 

IF cl_$match ('add[]'. command. command_len) THEN 

IF cl_$get_arg (cl_$next. name. name_len. sizeof (name)) THEN 
add_storage (name, address); 

IF cl_$match Cfree[]'. command. command_len) THEN 

IF cl_$get_arg (cl_$next. name. name_len. sizeof (name)) THEN 
free_storage (name, address); 

IF cl_$match ('q[uit]' # command. command_len) THEN 
pgm_$exit; 



END; 
UNTIL FALSE; < User types CTRL/Q > 
END. < manage_mapl_heap > 
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Introduction 



This part of Programming with DOMAIN Advanced System Calls is the Reference Section. It 
describes the data types, call syntax, and error messages for the programming calls described in 
Part I of this book. For your convenience, we structured this part like the DOMAIN System 
Call Reference manual: The sections are divided by system manager, arranged alphabetically 
by system manager name. 

If you prefer, you can insert these pages in the proper place within the reference manual. In cases 
where this book documents additional system calls to existing subsystems (for example, RWS) we 
duplicated the entire data types and error sections of the subsystem, marking the new material 
with change bars. 

The rest of this introduction describes the DOMAIN system insert files and the format of the 
information found in the sections that follow. 



DOMAIN Insert Files 



The DOMAIN system provides insert files that define data types, constants, values, and routine 
declarations. The insert files also define the exact form of each system call or routine. (Even the 
FORTRAN version does this using comments, although the FORTRAN compiler doesn't check 
the forms that you use.) 

To use system calls of a particular subsystem, you must specify the include file for that 
subsystem in your program. All insert files are located in the directory /SYS/INS/. For example, 
if you are using system error routines in a Pascal program, you include the insert file. 
/SYS/INS/ERROR.INS.PAS. Using the same routines in a FORTRAN program, you include 
/SYS/INS/ERROR.INS.FTN. All insert files are specified using the syntax 

/SYS/INS/subsystem-prefix.INS.language-abbreviation 

where the language abbreviation is PAS (Pascal), FTN (FORTRAN), or C (C). The listing. on 
the next page shows all the available insert files. 

In addition to including required subsystem insert files in a program, you must always include the 
BASE insert file for your programming language. These files contain some basic definitions that 
a number of subsystem routines use. 

You specify BASE insert files using the syntax 

/SYS/INS/BASE.INS.language-abbreviation 
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Summary of Insert Files 



Insert File 



Operating System Component 



/SYS/INS/BASE . INS . Ian 



Base definitions — must always be included 



/SYS/INS/ACLM . INS . Ian 
/SYS/INS/BAF . INS . Ian 
/SYS/INS/CAL . INS . Ian 
/SYS/INS/CL . INS . Ian 
/SYS/INS/ERROR . INS . Ian 
/SYS/INS/EC2 . INS . Ian 
/SYS/INS/FU . INS . Ian 
/SYS/INS/GM . INS . Ian 
/SYS/INS/GMF . INS . Ian 
/SYS/INS/GPR . INS . Ian 
/SYS/ INS/ IPC . INS . Ian 
/SYS/INS/KBD . INS . Ian 
/SYS/INS/LOADER . INS . Ian 
/SYS/ INS/LOGIN . INS . Ian 
/SYS/INS/MBX . INS . Ian 
/SYS/ INS/MS . INS . Ian 
/SYS/INS/MTS . INS . Ian 
/SYS/INS/MUTEX . INS . Ian 
/SYS/INS/NAME. INS . Ian 
/SYS/INS/PAD . INS . Ian 
/SYS/INS/PBUFS . INS . Ian 
/SYS/INS/PFM . INS . Ian 
/SYS/INS/PGM . INS . Ian 
/SYS/INS/PM . INS . Ian 
/SYS/INS/PR0C1 . INS .PAS 
/SYS/INS/PR0C2 . INS . Ian 
/SYS/INS/RWS . INS . Ian 
/SYS/INS/SIO . INS . Ian 
/SYS/INS/SMDU . INS . Ian 
/SYS/ INS/STREAMS . INS . Ian 
/SYS/INS/TIME . INS . Ian 
/SYS/INS/TONE.lan 
/SYS/INS/TPAD . INS . Ian 
/SYS/INS/VEC . INS . Ian 
/SYS/INS/VFMT . INS . Ian 



Access Control List manager 

Basic Allocate and Free manager 

Calendar manager 

Command Line Handler 

Error reporting manager 

Eventcount manager 

File and Tree Utility 

Graphics Metafile Resource 

Graphics Map Files manager 

Graphics Primitives manager 

Interprocess Communications datagrams 

[Useful constants for keyboard keys] 

Object module loader 

Login manager 

Mailbox manager 

Mapping server 

Magtape/streams interface 

Mutual exclusion lock manager 

Naming server 

Display manager 

Paste buffer manager 

Process fault manager 

Program manager 

User process routines 

Process manager (Pascal only) 

User process manager 

Read/write storage manager 

Serial I/O interface 

Display driver 

Stream manager 

Time manager 

Speaker manager 

Touchpad manager 

Vector arithmetic routines 

Variable formatter 
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Organizational Information 



This introductory section is followed by sections for each subsystem. The material for each 
subsystem is organized into the following three parts: 

1. Detailed data type information (including illustrations of records for the use of 
FORTRAN programmers). 

2. Full descriptions of each system call. Each call within a subsystem is ordered 
alphabetically. 

3. List of possible error messages. 
Data Type Sections 



A subsystem's data type section precedes the subsystem's individual call descriptions. Each data 
type section describes the predefined constants and data types for a subsystem. These 
descriptions include an atomic data type translation (i.e., TIME_$REL_ABS_T = 4-byte 
integer) for use by FORTRAN programmers, as well as a brief description of the type's purpose. 
Where applicable, any predefined values associated with the type are listed and described. The 
following is an example of a data type description for the RWS_$POOL_T type. 



DATA TYPES 



RWS_$POOL_T A 2-byte integer. Types of pools to allocate 

read /write or heap storage. One of the following 
pre-defined values: 

RWS_$STD_POOL 

Standard pool makes storage accessible to 

calling process only. 

RWS_$STREAM_TM_POOL 
Stream pool makes storage accessible to 
calling program and to a program invoked 
with the UNIX EXEC system call. 

RWS_$GLOBAL_POOL 

Global pool makes storage accessible to all 

processes. 

In addition, the record data types are illustrated in detail. Primarily, we have geared these 
illustrations to FORTRAN programmers who need to construct record-like structures, but we've 
designed the illustrations to convey as much information as possible for all programmers. 
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Each record type illustration does the following: 

• Clearly shows FORTRAN programmers the structure of the record that they must 
construct using standard FORTRAN data type statements. The illustrations show the 
size and type of each field. 

• Describes the fields that make up the record. 

• Lists the byte offsets for each field. These offsets are used to access fields 
individually. 

• Indicates whether any fields of the record are, in turn, predefined records. 

The following is the description and illustration of the PM_$SECT_INFO predefined record: 



Total 
Size: 40 



byte: 
offset 



0: 



Predefined 32: 

Record: 

PM $SECT INFO 36: 



31 




15 





field name 






char 


name 






*. 


* 




integer 


loc 


integer 


len 



NAME 

The name of the section, a character array of up 

to 32 elements. 

LOC 

A 4-byte integer. Location of section 

information. 

LEN 

A 4-byte integer. Length of section. 



FORTRAN programmers, note that a Pascal variant record is a record structure that may be 
interpreted differently depending on usage. In the case of variant records, as many illustrations 
will appear as are necessary to show the number of interpretations. 



r 
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System Call Descriptions 

We have listed the system call descriptions alphabetically for quick reference. Each system call 
description contains: 

• An abstract of the call's function. 

• The order of call parameters. 

• A brief description of each parameter. 

• A description of the call's function and use. 

These descriptions are standardized to make referencing the material as quick as possible. 

Each parameter description begins with a phrase describing the parameter. If the parameter can 
be declared using a predefined data type, the descriptive phrase is followed by the phrase ",in 
XXX format" where XXX is the predefined data type. Pascal or C programmers, look for this 
phrase to determine how to declare a parameter. 

FORTRAN programmers, use the second sentence of each parameter description for the same 
purpose. The second sentence describes the data type in atomic terms that you can use, such as 
"This is a 2-byte integer." In complex cases, FORTRAN programmers are referenced to the 
respective subsystem's data type section. 

The rest of a parameter description describes the use of the parameter and the values it may 
hold. 

The following is an example of a parameter description: 

heap_ptr 

Address of the created heap, in BAF_$T format. This is a 4-byte integer. A returned address 
of zero (NIL) means that BAF_$CREATE could not create a heap. 

Error Sections 

Each error section lists the status codes that may be returned by subsystem calls. The following 
information appears for each error: 

• Predefined constant for the status code. 

• Text associated with the error. 
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DATA TYPES 



BAF $OPTS T 



BAF_$T 




Total 
Size: 4 


byte: 
offset 


Predefined 
Record: 


:0 


UNIV PTR 





31 



A 4-byte integer. A set of BAF_$SHARED types. 
Indicates that the storage supplied to BAF is 
shared. 

A record of UNIV pointers which point to internal 
data structures. The diagram below illustrates the 
BAF_$T data type: 



15 



integer 



field name 



rep 



Field Description: 

REP 

Pointer to BAF internal data structures. 



STATUS $T 



A status code. The diagram below illustrates the 
STATUS_$T data type: 



Total byte: 

Size: 4 offset 31 



0: 

0: 

1: 
2: 



n31 



integer 



or 



24 
16 



integer 



field name 
all 

fail 
subsys 

mode 
code 



Field Description: 

ALL 

All 32 bits in the status code. 

FAIL 

The fail bit. If this bit is set, the error was not 



BAF 



BAF-2 



Apollo Confidential 



BAF DATA TYPES 



UNIV PTR 



within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

SUBSYS 

The subsystem that encountered the error (bits 

24 - 30). 

MODC 

The module that encountered the error (bits 16 - 

23). 

CODE 

A signed number that identifies the type of error 

that occurred (bits - 15). 

A 4-byte integer. A pointer to allocated storage. 
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BAF $ADD SPACE 



Adds more storage space to a basic allocate/free (BAF) heap that was previously created 
with BAF $CREATE. 



FORMAT 

BAF_$ADD_SPACE (heap, area, size, status) 

INPUT PARAMETERS 

heap 

The address of the heap to which the storage will be added, in BAF_$T format. This 
address is the return value of the function, BAF_$CREATE. 

area 

The address of the storage space to be added to the heap, in UNTV_PTR format. This is a 
4-byte integer. 

size 

The amount of space to be added. This is a 4-byte integer. The maximum size you can 
add at one time is 32K bytes. If you want to add more than 32K bytes, add the space in a 
separate call to BAF _$ADD_ SPACE. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. This data type is 4 bytes long. See the BAF 
Data Types for more information. 

USAGE 

Use this call to add storage to a basic alloc/free heap that you previously created with 
BAF_$CREATE. You can add up to 32K bytes per call. If you want to add more space to 
the heap, make another call to BAF _$ADD_ SPACE. 
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BAF_$ALLOC 

BAF_$ALLOC 

Allocates a contiguous region of storage from a basic allocate/free (BAF) heap. 

FORMAT 

pointer := BAF_$ALLOC (heap. size, status) 

RETURN VALUE 

pointer 

Address of the allocated storage space, in UNTV_PTR format. This is a 4-byte integer. A 
returned address of zero (NIL) means that BAF_$ALLOC could not allocate the desired 
storage from the specified heap. 

INPUT PARAMETERS 

heap 

Address of the heap from which storage will be allocated, in BAF_$T format. This 
address is the return value of the function, BAF_$CREATE. 

size 

Size of the new storage space to be allocated from the heap. This is a 4-byte integer. The 
maximum amount of space you can allocate at one time is 32K bytes. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the BAF 
Data Types section for more information. STATUS _$T will always return 
STATUS _$OK unless BAF_$ALLOC returns a value of NIL in the return parameter, 
"pointer." 

USAGE 

Use this call to allocate storage from the basic alloc/free heap that you created with 
BAF_$CREATE. This call allocates a contiguous region of storage of "size" bytes long. 
The storage space will be aligned on a 4-byte boundary. The overhead per allocation is 
currently 4 bytes long, but is subject to change. 
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BAF_$CREATE 

Create a basic alloc/free heap. 

FORMAT 

heap_ptr := BAF_$CREATE (options, area, size, status) 

RETURN VALUE 

heap_ptr 

Address of the created heap, in BAF_$T format. This is a 4-byte integer. A returned 
address of zero (NIL) means that BAF__$CREATE could not create a heap. 

INPUT PARAMETERS 

options 

BAF options in BAF_$OPS_T format. This is a 4-byte integer. Specify the predefined 
value: 

BAF_$SHARED 

Indicates that the storage space you supply to BAF is shared. Therefore, BAF_$ALLOC 
and BAF_$FREE must obtain a lock during their operations to prevent another process 
from corrupting the heap. For greater efficiency, specify BAF_$SHARED only when the 
storage is shared. 

area 

Address of storage space that BAF_$CREATE will use to create a heap in UNIV_PTR 
format. This is a 4-byte integer. 

size 

Size of the heap. This is a 4-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. STATUS _$T 
will always return STATUS _$OK unless BAF__$CREA'ixC returns a value of NIL in the 
return parameter, "heap_ptr." 

See the BAF Data Types section for more information. 

USAGE 

Use this call to create a basic alloc/free heap. You can use subsequent BAF system calls to 
allocate storage space from the heap (with BAF_$ALLOC), free storage space (with 
BAF__$FREE), and add more storage space to the heap (with BAF _$ADD_ SPACE). 
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BAF $FREE 



Returns a region of storage to a basic allocate/free (BAF) heap that was previously 
allocated with BAF _$ALLOC. 

FORMAT 

BAF_$FREE (heap, block, status) 

INPUT PARAMETERS 

heap 

The address of the heap from which storage will be freed, in BAF_$T format. This 
address is return value of the function BAF__$CREATE. 

block 

The address of the block of storage to be freed. This address is the return value of the 
function, BAF_$ALLOC. This is a 4-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. See the BAF Data Types section for more 
information. This data type is 4 bytes long. STATUS _$T will always return 
STATUS _$OK unless the specified block is not located in the specified heap. 

USAGE 

Use this call to free storage from the basic alloc/free heap that you previously allocated 
with- BAF _$ALLOC. This call fails if the block was not located in the heap, or if it was 
already free. 
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ERRORS 

B AF _ $FREED _ TWICE 

BAF_$FREE returns this error if you attempted to free a block that was previously 
freed. 

BAF_$NO_ROOM 

BAF_$ALLOC returns this error if there was not enough storage in the heap to 
allocate the blocks you specified. 

BAF _ $FORMAT_ VIOLATED 

This error occurs if the block overhead gets overwritten. It gets overwritten when 
another process overflows the bounds of an array, because the overhead is located just 
before each block. 
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CL DATA TYPES 
DATA TYPES 

CL_$OPT_T A 2-byte integer. Set of options that control how 

the CL reads the command line. List some of the 
following predefined values. (Note that some of 
these options are mutually exclusive; see the CL call 
syntax for details.) 

CL_$WILDCARDS 

Causes CL_$GET_NAME to resolve 

wildcards and return the resolved names 

(default). 

CL_$NO_WILDCARDS 

Causes CL_$GET_NAME to return 

wildcard names verbatim, it does not resolve 

them. 

CL_$VERIFY_NONE 

CL_$GET_NAME does not verify any 

names with the user, (default). 

CL_$VEREFY_ALL 

CL_$GET_NAME verifies all names with 

the user. 

CL_$VERIFY_WILD 

CL_$GET_NAME verifies only names 

resolved by wildcards with the user. 

CL_$DASH_NOP 

Causes CL to treat the hyphen as a name. 
Normally, the hyphen is an identifier for the 
standard input stream (default). 

CL_$DASH_NAMES 

Causes CL to read names from standard input 
if no arguments appear on the command line. 
(Obsolete for new program development.) 

CL_$DASH_DFT_NOP 

Suppresses any special action when there are 

no arguments on the command line (default). 

CL_$NAME_DFT_STDIN 

Causes CL to read names from standard input 

if no arguments appear on the command line. 

CL_$NO_MATCH_OK 

Displays no warning or error message when a 

wildcard does not match existing pathnames. 

CL_$NO _MATCH_ WARNING 

Displays a warning message on error output 
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when a wildcard does not 
pathnames (default). 



match existing 



CL_$NO_MATCH_ERROR 
Displays an error message on error output and 
terminates the program when a wildcard does 
not match an existing pathname. 

CL_$KEYWORD _DELIM 

Prevents CL_$GET_ARG and 

CL__$GET_NAME from returning an 

"unused" keyword as an argument. The calls 

return FALSE if they encounter a keyword. 

(default). 

CL_$NO_KEYWORD_DELIM 
Causes no special treatment of unread 
keywords by CL_$GET_ARG and 
CL_$GET_NAME. CL procedures return 
the keywords as if they were arguments. 

CL_$COMMENTS 

Causes CL to ignore all characters enclosed in 
brackets when reading a names-file. Do not 
use this option for commands that accept 
derived names. 



CL $OPT SET T 



CL_$NO_ COMMENTS 

Causes no special treatment of characters 

enclosed in brackets (default). 

CL _ ISTAR _ NAMES 

Allows the user to specify names-files on the 

command line for CL to resolve (default). 

CL_$NO_STAR_NAMES 

Does not allow the user to specify names-files 
on the command line; CL treats the "*" like 
any other character. 

A 4-byte integer. A set of CL options in 
CL_$OPT_T format. For a list of options, see 
CL $OPT T above. 
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CL_$ARG_ SELECT _T A 2-byte integer. Determines whether CL begins a 

search at the current token pointer or at the top of 
the token list. One of the following pre-defined 
values: 

CL_$FIRST 

Search begins before the first unused token on 

the token list. 

CL_$NEXT 

Search begins at the current token pointer on 

the token list. 

CL_$ANSWER_T A 2-byte integer. The answer that the user supplies 

when CL performs a query. One of the following 
pre-defined values: 

CL_$YES 

User confirms pathname. 

CL_$NO 

User cancels pathname, so CL ignores it. 

CL_$QUIT 

User tells CL to verify any names. 

CL_$GO 

User tells CL to continue processing names 

without verifying them. 

CL_$REQUIRED_T A 2-byte integer. Determines whether the user 

needs to supply a derived name after a keyword in 
the CL _ $GET _FLAGGED _DERIVED _ NAME 
call. One of the following pre-defined values: 

CL_$REQUIRED 

Requires that the user supplies a derived name 

after the specified flag. If absent, the program 

terminates. 

CL_$OPTIONAL 

User has the option to specify a derived name 

after a specified keyword. If the user supplies 

a derived name, it returns TRUE, and the 

derived name. If the user does not supply a 

derived name, it returns TRUE, but with no 

name. 
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CL $WILD T 



A 2-byte integer. Set of wildcard options that 
determine how the wildcard manager resolves 
wildcards. One of the following pre-defined values: 



CL_$WILD_FILES 
Returns the names of files. 

CL_$WILD_DIRS 

Returns the names of directories. 

CL_$WILD_LINKS 
Returns the names of links. 

CL_$WILD_EXCLUSIVE 

Traverses each branch of the naming tree as 

far as the first wildcard match. This is useful 

for commands that operate on entire 

directories, such as COPY _ TREE, or 

WRITE_BACKUP. 

CL_ $WILD _ CHASE_LINKS 

Chases links that point to directories. 



CL $WILD SET T 



CL_$WILD_FIRST 

Stops at the first match of a given wildcard, 

rather than resolving all names. 

A 2-byte integer. A set of wildcard options in 
CL_$WILD_T format. For a list of options see 
CL $WILD T above. 



CL $ARGV 



An argument returned by CL_$PARSE_ARGS. 
The diagram below illustrates the CL_$ARV data 
type: The diagram below illustrates the 

CL_$ARGV data type: 



Total 
Size: 128 



byte: 
offset 





15 


0: 


integer 


2: 


char 


> 


* * 


127: 


char 



field name 

len 
chars 



Field Description: 

LEN 

Length of the argument. 
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CHARS 

The text of the argument, a character array of 

up to 128 elements. 

CL_$ATTR_SET_T A 2-byte integer. An element set, 0..15, based on 

the contents of two character strings. 
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CL_$CHECK_FLAG 

Checks the command line to see if the user specified a flag. It counts the number of tokens 
following it that are not flags. 

FORMAT 

found := CL_$CHECK_FLAG(flag_string, tokens_expected) 

RETURN VALUE 

found 

Returns TRUE if flag _ string is found; returns FALSE if not. 

INPUT PARAMETERS 

flag_8tring 

The flag (a token preceded by a hyphen) you want the CL to search for. This is a lowercase 
character string in the UNIV character string format. You specify the flag in the form of 
"-required [optional] . " 

"-required" represents the characters of the flag that the user must type, "[optional]" 
represents those characters that are optional. If the user specifies any optional characters, 
they all must be specified. 

If you do not specify any optional characters, you must supply an empty bracket, []. 

For example, M -arg[uments] M matches "-arg" or "-arguments. " "-ld[]" matches "-Id." 

tokens _ expected 

The number of tokens that you expect to follow the specified flag. This is a 2-byte integer. 
If you supply a negative number, the CL assumes that you want at least that many 
arguments, but will accept more. 

USAGE 

Use this call to check if the user supplied the correct number of options. 

The call searches the token list for a specified flag bx-.z. returns a Boolean indicating whether 
the flag was found. It also tests for the expected number of arguments following the flag. 

If the user does not supply the number of tokens expected, the CL returns an error and calls 
PGM_$EXIT to terminate the program. If it finds the flag, the CL marks it "used," and 
moves the token pointer to the flag. Otherwise, the token pointer remains unchanged. 

Normally, you do not need to know whether the user typed the abbreviated or full flag. 
However, you can find out what the user typed with the CL__$GET__ FLAG _ INFO system 
call. 

NOTE: Do not use this call if tokens can go anywhere on a command line 
because you might get unexpected results. In this case, 
use CL $GET FLAG. 
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CL_ $CHECK_UNCLAIMED 

CL _ $CHECK_UNCLAIMED 

Checks the token list for any unread flags. If it finds any, this call prints an error message I 

and terminates the program. 

FORMAT 

CL_$CHECK_UNCLAIMED 

USAGE 

Use this call to check if the user specified any options that your program does not handle. 
If so, the program aborts. 

Most programs use this call before calling CL_$GET_NAME. Do not use this call if you 
plan to use CL_$GET_FLAGGED_DERIVED_NAME. 
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CL_$GET_ARG 

CL_$GET_ARG 

Gets the first or next unused argument from the token list. 

FORMAT 

found := CL_$GET_ARG(selector. arg. arg_len. max_len) 

RETURN VALUE 

found 

Returns TRUE if it finds an argument; returns FALSE if not. 

INPUT PARAMETERS 

selector 

Determines where the CL begins to scan the token list, in CL_$ARG_ SELECT _T 
format. This is a 2-byte integer. 

You must specify one of the following: 

CL_$FIRST Directs the CL to return to the first unused token on the token list to 
begin the search. 

CL_$NEXT Directs the CL to scan the token list beginning with the argument 
following the token pointer. 

max_len 

The maximum number of characters to place into "arg." This is a 2-byte integer. If the 
argument contains too many characters, the CL prints an error message and calls 
PGM_$EXIT to terminate the program. 

OUTPUT PARAMETERS 

arg 

Returns the argument that CL finds on the token list, in character string format. 

arg _ len 

Returns the actual length of the argument, as a 2-byte integer. 

USAGE 

Use this call to get arguments from the command line. You can then convert the character 
strings to the desired type. If you expect pathnames from the command line, use 
CL_$GET_NAME because CL_$GET_NAME resolves wildcards. If you expect 
numbers from the command line, use CL_$GET_NUM. 

CL_$GET_ARG reads a token from the token list. If it finds an argument, the CL 
marks it used, and moves the token pointer to it. If it doesn't find any arguments, the CL 
sets the token pointer to top of the list, before the first token. 
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CL $GET ARG 



If the token is a flag and the default CL option CL_$KEYWORD_DELIM is in effect, the 
CL returns FALSE. If the token is a flag and you set the CL option 
CL_$NO_ KEYWORD _DELM the call returns TRUE, and the value of "arg." This is 
useful if you want to read tokens that begin with a hyphen but you don't want to treat 
them as flags. 
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CL $GET DERIVED NAME 



Gets the next derived name that applies to the name most recently read by 
CL $GET NAME. 



FORMAT 

found := CL_$GET_DERIVED_NAME(name. name_len. max_len) 

RETURN VALUE 

found 

Returns TRUE if it finds a name; returns FALSE if not. 

INPUT PARAMETERS 

max_len 

The maximum number of characters to place into "name." This is a 2-byte integer. If the 
name contains too many characters, the CL prints an error message and calls PGM_$EXIT 
to terminate the program. 

OUTPUT PARAMETERS 

name 

Returns the name the CL found, in character string format. This is valid only if "found" is 
TRUE. 

name_len 

Returns the actual length of the name, as a 2-byte integer. 

USAGE 

Use this call after CL_$GET_NAME to get a derived name. Do not use in programs if 
you do not expect derived names. 

Each time you call CL_$GET_NAME, the CL sets a "derived-name pointer" next to the 
token pointer. Each subsequent call to CL_$GET_DERIVED_NAME, advances the 
derived-name pointer to the next derived name, until there are none left. 

A single derived name may be seen by a program a number of times. For example, the 
command line, cpf ?*.pas =.05.31, matches all instances in the working directory of files 
ending with the .pas extension. The program sees the derived name, not the token. For 
example, if it finds the pathname foo.pas, CL_$GET_DERIVED_NAME returns 
foo.pas.05.31. 

CL_$GET_DERIVED_NAME does not change the token pointer. Once a token is used 
as a derived name, it is marked "used," and is not returned by CL_$GET_NAME or 
CL_$GET_ARG again. 
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CL _ $GET _ENUM_FLAG 

Scans the token list for any member of a list of flags that you supply. It counts the number 
of tokens following it which are not flags. 

FORMAT 

index := CL_$GET_ENUM_FLAG (selector, flag_list, token_count) 

RETURN VALUE 

index 

Returns the index of the flag in the " flag _ list," if found; returns zero if it does not find 
any of the specified flags. 

INPUT PARAMETERS 

selector 

Determines where the CL begins to scan the token list, in CL_$ARG_ SELECT __T 
format. This is a 2-byte integer. 

You must specify one of the following: 

CL_$FIRST Directs the CL to return to the first unused token on the token list to 
begin the search. 

CL_$NEXT Directs the CL to scan the token list beginning with the argument 
following the token pointer. 

flag _ list 

The flags you want the CL to search for. This is a lowercase character string, where each 
flag is in the form of "-required [op tional].** 

"-required" represents the characters of the flag that the user must type, "optional" 
represents those characters that are optional. If the user specifies any optional characters, 
they all must be specified. 

If you do not specify any optional characters, you must supply an empty bracket, []. For 
example, "-arguments]" matches "-arg" or "-arguments." "-ld[] M matches "-Id". 

You must separate each flag by spaces, and terminate the string with any non-space 
character other than a hyphen. For example, "-br[ief] -l[ist] X". 

OUTPUT PARAMETERS 

token _ count 

Returns the number of tokens that follow the flag up to the next flag. This 2-byte integer is 
valid only if "index" does not equal zero. 

Note that this is the number of tokens listed on the command line only. It does not count 
the number of names resolved from a wildcard name. 
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USAGE 



Use this call when the user can supply different options that require the same program 
action. 

The call searches the token list for specified flags from the "flag_list." If the user specifies 
more than one flag that is on the list, the CL returns only the first one it matches. 

If it finds the flag, the CL marks it "used," and moves the token pointer to the flag. 
Otherwise, the token pointer remains unchanged. 

Normally, you do not need to know whether the user typed the abbreviated or full flag, 
However, you can find out what the user typed with the CL _$GET_ FLAG _ INFO call. 
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CL_$GET_FLAG 

Checks the command line to see if the user specified a flag, which is a token preceded by a 
hyphen. It counts the number of tokens following it which are not flags. 

FORMAT 

found := CL_$GET_FLAG(flag_string. token_count) 

RETURN VALUE 

found 

Returns TRUE if ■ flag _ string" is found; returns FALSE if not. 

INPUT PARAMETERS 

flag _ string 

The flag you want the CL to search for. This is a lowercase character string in the form of 
" -required [optional] . " 

"-required" represents the characters of the flag that the user must type, "optional" 
represents those characters that are optional. If the user specifies any optional characters, 
they all must be specified. 

If you do not specify any optional characters, you must supply an empty bracket, []. 

For example, M -arg[uments]" matches "-arg" or "-arguments"; M -ld[]" matches "-Id". 

OUTPUT PARAMETERS 

token _ count 

Returns the number of tokens that follow the flag up to the next flag. This 2-byte integer is 
valid only if the call returns TRUE. 

Note that this is the number of tokens listed on the command line only. It does not count 
the number of names resolved from a wildcard name. 

USAGE 

Use this call when you want to get any specific flag from the command line. This call 
searches the token list for the specified flag and returns a Boolean indicating whether the 
flag was found. 

If it finds the flag, the CL marks it "used," and moves the token pointer to the flag. If not, 
the token pointer remains unchanged. 

This is the most commonly used call for getting flags from the command line. See also 
CL_$CHECK__FLAG and CL_$GET_ENUM_FLAG for other ways of getting flags. 
You can use CL__$GET_INFO to see which flags the user provided. 



z' 
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CL_ $GET_FLAGGED _DERIVED _ NAME 

CL_$GET_FLAGGED_DERIVED_NAME 

Scans the token list for a specified flag followed by a derived name. If a derived name 
follows the flag, it returns the name found. 

FORMAT 

found := CL_$GET_FLAGGED__DERIVED__NAME(flag. required_name, name, 

name_len. max_len) 

RETURN VALUE 

found 

Returns TRUE if it finds a name; returns FALSE if not. 

INPUT PARAMETERS 

flag 

The flag you want the CL to search for. This is a lowercase character string in the form of 
"-required [optional] . M 

"-required" represents the characters of the flag that the user must type, "optional" 
represents those characters that are optional. If the user specifies any optional characters, 
they all must be specified. 

If you do not specify any optional characters, you must supply an empty bracket, []. 

For example, "-arguments]" matches "-arg" or "-arguments"; "-ld[|" matches "-Id". 

required _ name 

Specifies whether a derived name must follow the flag, in CL_$REQUIRED__T format. 
This is a 2-byte integer. 

If you supply CL_$REQUIRED, and a derived name does not follow the flag, the CL 
returns an error message and terminates the program. If you supply CL_$OPTIONAL, 
and a derived name does not follow the flag, the CL returns TRUE, but does not return a 
name. 

max_len 

The maximum number of characters to place into "name." This is a 2-byte integer. If the 
name contains too many characters, the CL prints an error message and calls PGM_$EXIT 
to terminate the program. 

OUTPUT PARAMETERS 

name 

Returns the derived name the CL found, in character string format. This is valid only if 
"found" is TRUE. 

name_len 

Returns the actual length of the name. This is a 2-byte integer. If CI,/_$OPTIONAL is 
specified and a derived name does not follow the flag, "name_len" is set to zero. 
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USAGE 



Use this call after CL_$GET_NAME to check for a specific flag followed by a derived 
name. You can call CL _$GET_ FLAGGED _ DERIVED _ NAME either before or after 
calling CL_$GET_DERIVED_NAME. 

A single derived name may be seen by a program a number of times. For example, the 
command line, cmf {?*}.04.30 @1 -r @l.rpt is handled by three calls: 
CL_$GET_NAME resolves the wildcard to match all instances of files in the working 
directory ending with the .04.30 extension. CL_$GET_DERIVED__NAME gets each 
derived name, which is the wildcard match without the extension. Then 
CL_$GET_FLAGGED_DERIVED_NAME adds the rpt extension. 

CL__$GET_FLAGGED_DERIVED_NAME does not change the token pointer, or 
derived-name token pointer. Once a token is used as a derived name, the CL marks it 
"used," and does not return it to by CL_$GET_NAME or CL_$GET_ARG again. 

NOTE: Do not search for this flag with CL_$GET_FLAG if 
you plan to use this call . 



V... 
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CL_$GET_FLAG_INFO 

CL_$GET_FLAG_INFO 

Returns a pointer to the text of the last flag found by CL_$GET_FLAG, 
CL_$CHECK_FLAG, CL_$GET_ENUM_FLAG. 

FORMAT 

CL_$GET_FLAG_INFO (f lag_ptr . f lag_len) 

OUTPUT PARAMETERS 

flag_ptr 

Returns pointer to the character string containing the text of the flag. If the user did not 
specify a flag, it returns NIL. 

flag_len 

Number of characters in the character string pointed to by "flag_ptr." This is a 2-byte 
integer. This value is undefined if "flag_ptr" is NIL. 

USAGE 

Use this call to see which flag the user actually specified. You might want to return this 
text with an error message. 
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CL_$GET_NAME 

Gets the first or next unused name from the token list. 

FORMAT 

found := CL_$GET_NAME (selector, name, name_len. max_len) 

RETURN VALUE 

found 

Returns TRUE if it finds a name; returns FALSE if not. 

INPUT PARAMETERS 

selector 

Determines where the CL begins to scan the token list, in CL_$ARG_ SELECT _T 
format. This is a 2-byte integer. 

You must specify one of the following: 

CL_$FIRST Directs the CL to return to the first unused token on the token list to 
begin search. 

CL_$NEXT Directs the CL to scan the token list beginning with the argument 
following the token pointer. 

max_len 

The maximum number of characters to place into "name." This is a 2-byte integer. If the 
name contains too many characters, the CL prints an error message and calls PGM_$EXIT 
to terminate the program. 

OUTPUT PARAMETERS 

name 

Returns the name the CL found, in character string format. This is valid only if "found" is 
TRUE. 

name_len 

Returns the actual length of the name, as a 2-byte integer. 

USAGE 

Use this call to get names from the command line. If it finds a name, the CL marks it 
"used" and moves the token pointer to it. If it doesn't find any names, the CL moves the 
token pointer to top of the list, before the first token. 

CL__$GET__NAME reads a token from the token list. If the token is a pathname, it 
returns the pathname verbatim. If it is a wildcard name and the default 
CL_$WILDCARD option is in effect, the CL resolves the wildcard and returns the first 
pathname that matches. Subsequent calls to CL_$GET_NAME return successive 
pathnames resulting from the wildcard. 
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If the token is a flag and the default CL_$KEYWORD_DELIM option is in effect, the call 
returns FALSE; therefore, preventing the call from returning an unused flag as a name. 

If CL_$NO_ KEYWORD _DELIM option is set and the token is a flag, the call returns 
TRUE, and the flag verbatim. 

If you set one of the CL verify options VERIFY_$WILD or VERIFY_$ALL, this call 
queries the user for a yes/no approval. If the user answers "no," the CL ignores the name 
and processes the next name. 

If the call does not find a match for a wildcard-name, CL consults the current state of the 
CL match option to determine whether it should terminate the program with a warning or 
error message, or should continue. 

Normally, you do not need to know whether the token was a pathname or wildcard-name. 
However, you can find out exactlly what the user typed with the CL_$GET_INFO system 
call. 



/"~\ 
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CL_$GET_NAME_INFO 

Determines if the previous CL_$GET_NAME operated on a wildcard. If so, the call 
returns a pointer to the wildcard name. 

FORMAT 

CL_$GET_NAME_INFO(vild_ptr. vild_len) 

OUTPUT PARAMETERS 

wild_ptr 

Returns a pointer to the character string containing the wildcard name. If the user did not 
specify a wildcard name, it returns NIL. This is a UNIV_PTR. 

wild__len 

Length of the character string pointed to by "wild_ptr." This is a 2-byte integer. This 
value is undefined if M wild_ptr M is NIL. 

USAGE 

Use this call to determine whether the user supplied a full pathname or a wildcard name on 
the command line. 



/-"- 
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CL_$GET_NUM 
) Checks the token list for a decimal numeric argument and converts it to a 4-byte integer. 

FORMAT 

found := CL_$GET_NUM (number) 

RETURN VALUE 

found 

Returns TRUE if it finds a number; returns FALSE if not. 

OUTPUT PARAMETERS 

number 

Returns a long integer (integer32) containing the decimal numeric argument. This is a 

4-byte integer. 

USAGE 

Use this call to convert the argument following the token pointer to a long decimal. If the 
argument is not a decimal number, CL_$GET_NUM prints an error message and calls 
PGM_$EXIT to terminate the program. 

If the CL finds a number, the CL marks it "used" and moves the token pointer to it. 
Otherwise, the token pointer remains unchanged. 
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CL_$GET_SET 

Builds a 16-element set from a character string. 

FORMAT 

set :=CL_$GET_SET(char_string. string_len. token, token_len) 

RETURN VALUE 

set 

Returns the set, in the CL_$ATTR_SET_T format. This is a 2-byte integer. 

INPUT PARAMETERS 

char _ string 

Character string that defines the allowable token characters and their order in the returned 
set. This is in UNTV string format. The first character corresponds to the returned set 
element "0", the second element, to element "1," and so on. 

string _len 

Number of characters in "char __ string." This is a 2-byte integer. 

token 

Token, usually read from the token list, with which to build the set. This is a UNIV 
character string. 

token _len 

Number of characters in "token." This is a 2-byte integer. 

USAGE 

Use this call to build a set from a character string. For example, EDACL turns the 
character string "PGNDWKX" into a set for setting ACLs. 
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CL $INIT 



Initializes the command line handler that parses command lines, 
before any other CL calls. 



You must use this call 



FORMAT 

CL_$INIT([cl_option] . program_name . program__len) 



INPUT PARAMETERS 

cl_ option 

Set of options, in CL_$OPT_SET_T format, that tells the CL how to read the command 
line. This is a 4-byte integer. The options control how the CL interacts with the user. 

You can specify a default set of options with empty brackets, []. You need to specify only 
the options that are not default. The chart below lists the default CL options and their 
alternatives. Note that you can either take the default option, or specify one of its 
corresponding alternatives. 



Default Option 


Mutually- Exclusive Alternatives 


CL_$WILDCARDS 

Causes CL_$GET_NAME to resolve 

wildcards and return the resolved 

names. 


CL_$NO_WILDCARDS 
Causes CL_$GET_NAME to return 
wildcard-names verbatim; it does 
not resolve them. 


CL_$NO_MATCH_WARNING 
Displays a warning message on 
error output when a wildcard 
does not match existing 
pathnames. 


CL_$NO_MATCH_OK 
Displays no warning or error 
message when a wildcard does not 
match existing pathnames. 

CL_$NO_MATCH_ERROR 
Displays an error message on 
error output, and terminates 
the program when a wildcard 
does not match an existing 
pathname. 


CL_$VERJFY_NONE 
CL_$GET_NAME does not 
verify any names with the 
user. 


CL _ $VERIFY_ WILD 
CL_$GET_NAME verifies 
only names resolved by 
wildcards with the user. 

CL_$VERIFY_ALL 
CL_$GET_NAME verifies all 
names with the user. 
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Default Option 


Mutually-Exclusive Alternatives 


CL_$STAR_NAMES 
Allows user to specify 
names-files with the 
"*" operator. 


CL_$NO_STAR_NAMES 
Does not allow user to 
specify names-files. Treats the 
"*" just like any other character. 


CL _ $KEYWORD _ DELIM 
Prevents CL_$GET__ARG 
and CL_$GET_NAME 
from returning an "unused" 
flag as an argument. The 
calls return FALSE if they 
find a flag. 


CL_$NO_KEYWORD_DELIM 
Causes no special treatment 
of unread flags by 
CL_$GET_ARG and 
CL_$GET_NAME. The procedures 
return the flags as if they 
were arguments. 


CL_$DASH_NOP 
The CL treats the hyphen "-" as a 
name. Normally, the hyphen is an 
identifier for the standard 
input stream. 


CL_$DASH_NAMES 
The CL reads names from 
standard input when it finds 
a hyphen.* 


CL_$DASH_DFT_NOP 
Suppresses any special action when 
there are no arguments on the 
command line. 


CL_$NAME_DFT_STDIN 
Causes the CL to read names 
from standard input if no arguments 
appear on the command line.* 


CL _ $NO _ COMMENTS 
Causes no special treatment 
of characters enclosed 
in brackets. 


CL_$COMMENTS 

Causes CL to ignore all 1 

characters enclosed in brackets 

when reading a names-file. Do not J 

use this in commands that accept 

derived names because you must 

use brackets to specify the 

tag expressions you want to 

use in a derived name. 



* Made available to remain compatible with previous software releases. 
Obsolete for new software development. 

program _ name 

Name of program, in character string format. CL uses this name when reporting any 
errors. 

program _len 

Length of " program _ name". This is a 2-byte integer. 

USAGE 

Use this call to initialize the CL. This call reads the command line and any names-files that 
the user supplies and builds an internal token list that contains these tokens. All 
subsequent CL calls refer to this token list, not the command line. 
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CL_$MATCH 

Compares a token against a specified string and returns TRUE if they match. 

FORMAT 

match := CL_$MATCH (pattern, token, token_len) 

RETURN VALUE 

match 

Returns TRUE if it finds a match; returns FALSE if not. 

INPUT PARAMETERS 

pattern 

Pattern with which to compare the token. This is a lowercase UNIV character string in the 
form of "required [optional]." 

"required" represents the characters of the flag that the user must type, "optional" 
represents those characters that are optional. If the user specifies any optional characters, 
they all must be specified. 

If you do not specify any optional characters, you must supply an empty bracket, []. 

For example, "q[uitj" matches "q" or "quit." "go[]" matches "go." 

token 

Character string to compare against the pattern. This is a lowercase character string in 
UNIV character string format. 

token _len 

The number of characters to place in "token." This is a 2-byte integer. 

USAGE 

Use this call to compare a string against a specification. For example, this allows you to 
perform an action as soon as the user types the command. The following example uses 
CL__$MATCH in an interactive parsing loop to exit the program as soon as the user types 
a response: 

cl_$parse_line ( line. line_len ); 

< Terminate program if user types a q[uit] . > 

IF cl_$get_arg (cl_$first. token. token_len. sizeof (token_len) THEN 

IF cl_$match Cq[uit]'. token. token_len THEN 

pgm_$exit 
ELSE IF cl $match ( . . . 
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CL_$PARSE__ARGS 



Takes the specified argument vector, and makes it the current vector for the CL to parse. 
The CL discards any previous arguments. All subsequent CL calls operate on this argument 
list. 



FORMAT 

CL_$PARSE_ARGS(arg_count, arg_vector) 

INPUT PARAMETERS 

arg_ count 

Number of arguments in the argument vector. This is a 2-byte integer. 

arg_ vector 

Address of the argument vector to parse, in CL_$ARGV format. This is a 4-byte integer. 
It is a UNTV array of pointers to arguments in a record. 

USAGE 

Use this call when you use PGM_$GET_ARGS to get arguments from the command line. 
Use CL_$SETUP to initialize the CL when you want to supply the lines to parse. 

Note that this call disregards the first argument on the command line because it assumes it 
is the command name. 
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CL _ $PARSE_ INPUT 
( i Parses a line of text from a specified stream and passes the line to CL__$PARSE_LINE. 

FORMAT 

ok := CL_$PARSE_INPUT(stream_id, null_line) 

RETURN VALUE 

ok 

Returns TRUE if it reads the line from the stream successfully; returns FALSE if it 
encounters an end-of-file. If any other errors occur, the CL prints an error message, and 
calls PGM_$EXIT to terminate the program. 

INPUT PARAMETERS 

8tream__id 

Stream ID of the stream from which the line is read, in STREAM_$ID_T format. 

OUTPUT PARAMETERS 

null _ line 

Indicates whether the line is NULL (that is, the line contains only the NEWLINE 
character). This is a Boolean value. 

^~\. The call returns TRUE if the line read is NULL; returns FALSE if the line is not NULL. 

USAGE 

You can use this call and CL_$PARSE_LINE so that you can use other CL calls to read 
tokens that the user inputs interactively. 

Use CL_$SETUP to initialize the CL when you want to supply the lines to parse. 
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CL_$PARSE_LINE 



Parses a line of text and creates a new token list. All subsequent CL calls operate on this 
line. 



FORMAT 

CL_$PARSE_LINE(text. null_line) 

INPUT PARAMETERS 

text 

Character string to be parsed. This is in UNTV character string format. 

text_len 

Number of characters in "text." This is a 2-byte integer. 

USAGE 

Use this call if the lines of text you want to parse are contained in files. Use CL_$SETUP 
to initialize the CL when you want to supply the lines to parse. 
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CL_$REREAD 

Marks the entire token list "unused," so that you can reread the entire token list. 

FORMAT 

CL_$REREAD 

USAGE 

Use this call to reread the entire command line. If you want to reread only the flags on the 
token list, use CL__$REREAD_ FLAGS. If you want to reread only the names, use 
CL $REREAD NAMES. 
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CL _ $REREAD _ FLAGS 



Locates all the "used" flags on the token list and marks them "unused." This allows you 
to reread all the flags. 



FORMAT 

CL_$REREAD_FLAGS 

USAGE 

Use this call to reread the flags on token list after having read them using 
CL_$GET_FLAG, CL_$CHECK_FLAG or CL_$GET_ENUM_FLAG. 

To reread the entire token list, use CL_$REREAD. 
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CL _ $REREAD _ NAMES 

Locates all the "used" names on the token list and marks them "unused." This allows you 
to reread all the names using CL_$GET_NAME. 

FORMAT 

CL_$REREAD_NAMES 

USAGE 

Use this call to reread the names on the token list after having read them with 
CL_$GET_NAME. 

When you call CL_$GET_NAME after this call, it returns the first name on the token 
list. 

To reread the entire token list, use CL_$REREAD. 
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CL _ $RESET_ OPTIONS 

Replaces the previously defined CL option set with the set specified in this call. 

FORMAT 

CL_$RESET_OPTIONS ( [cl__option] ) * 

INPUT PARAMETERS 

cl_ option 

Set of options, in CL_$OPT_SET_T format, that tells the CL how to read the command 
line. This is a 4-byte integer. These options control how the CL interacts with the user. 

You must specify all the options you want in effect, except the default options. 

The chart below lists the default CL options and their alternatives. Note that you can take 
either one of the default options, or specify one of the corresponding alternatives. 



Default Option 


Mutually- Exclusive Alternatives 


CL_$WILDCARDS 

Causes CL_$GET_NAME to resolve 

wildcards and return the resolved 

names. 


CL_$NO_WILDCARDS 
Causes CL_$GET_NAME to return 
wildcard-names verbatim; it does 
not resolve them. 


CL_$NO_MATCH_WARNING 
Displays a warning message on 
error output when a wildcard 
does not match existing 
pathnames. 


CL_$NO_MATCH_OK 
Displays no warning or error 
message when a wildcard does not 
match existing pathnames. 

CL _ $NO _MATCH _ERROR 
Displays an error message on 
error output, and terminates 
the program when a wildcard 
does not match an existing 
pathname. 


CL_$VERIFY_NONE 
CL_$GET_NAME does not 
verify any names with the 
user. 


CL_$VERIFY_WILD 
CL_$GET_NAME verifies 
only names resolved by 
wildcards with the user. 

CL_$VERIFY_ALL 
CL_$GET_NAME verifies all 
names with the user. 
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Default Option 


Mutually- Exclusive Alternatives 


CL_$STAR_NAMES 
Allows user to specify 
names-files with the 
"*" operator. 


CL_$NO_STAR_NAMES 
Does not allow user to 
specify names-files. Treats the 
"*" just like any other character. 


CL _ $KEYWORD _DELIM 
Prevents CL_$GET__ARG 
and CL_$GET_NAME 
from returning an "unused" 
flag as an argument. The 
calls return FALSE if they 
find a flag. 


CL _ $NO _KEYWORD _DELIM 
Causes no special treatment 
of unread flags by 
CL_$GET_ARG and 
CL_$GET_NAME. The procedures 
return the flags as if they 
were arguments. 


CL_$DASH_NOP 
The CL treats the hyphen "-" as a 
name. Normally, the hyphen is an 
identifier for the standard 
input stream. 


CL_$DASH_NAMES 
The CL reads names from 
standard input when it finds 
a hyphen.* 


CL_$DASH_DFT_NOP 
Suppresses any special action when 
there are no arguments on the 
command line. 


CL_$NAME_DFT_STDIN 
Causes the CL to read names 
from standard input if no arguments 
appear on the command line.* 


CL _ $NO _ COMMENTS 
Causes no special treatment 
of characters enclosed 
in brackets. 


CL_$COMMENTS 
Causes CL to ignore all 
characters enclosed in brackets 
when reading a names-file. Do not 
use this in commands that accept 
derived names because you must 
use brackets to specify the 
tag expressions you want to 
use in a derived name. 



* Made available to remain compatible with previous software releases 
Obsolete for new software development. 



USAGE 



Use this call to replace the set of CL options defined with the calls CL_$INIT, 
CL_$SETUP, or CL_$SET_ OPTIONS. CL_$RESET_ OPTIONS replaces the 
currently defined CL option set with the set specified in this call. If you want to simply 
add to the existing set of options, use CL_$SET_ OPTIONS. 



Apollo Confidential 



CL-33 



CL 
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CL_$SETUP 

Initializes the command line handler, but does not load anything to parse. Use this call 
instead of CL__$INIT when you want to use one of the CL parse routines. 

You must use either this call or CL_$INIT before any other CL calls. 

FORMAT 

CL_$SETUP([cl_option] . program_name . program_len) 

INPUT PARAMETERS 

cl__ option 

Set of options, in CL_$OPT_SET__T format, that tells the CL how to read the command 
line. This is a 4-byte integer. These options control how the CL interacts with the user. 

You can specify a default set of options with empty brackets, []. You need to specify only 
the options that are not default. The chart below lists the default CL options and their 
mutually-exclusive alternatives. 



Default Option 


Mutually- Exclusive Alternatives 


CL_$WILDCARDS 

Causes CL_$GET_NAME to resolve 

wildcards and return the resolved 

names. 


CL _ $NO _ WILDCARDS 
Causes CL_$GET_NAME to return 
wildcard-names verbatim; it does 
not resolve them. 


CL _ $NO _MATCH _ WARNING 
Displays a warning message on 
error output when a wildcard 
does not match existing 
pathnames. 


CL_$NO_MATCH_OK 
Displays no warning or error 
message when a wildcard does not 
match existing pathnames. 

CL _ $NO _MATCH_ERROR 
Displays an error message on 
error output, and terminates 
the program when a wildcard 
does not match an existing 
pathname. 


CL_$VERIFY_NONE 
CL_$GET_NAME does not 
verify any names with the 
user. 


CL_$VERIFY_WILD 
CL _ $GET _ NAME verifies 
only names resolved by 
wildcards with the user. 

CL_$VERIFY_ALL 
CL_$GET_NAME verifies all 
names with the user. 
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Default Option 


Mutually-Exclusive Alternatives 


CL_$STAR_NAMES 
Allows user to specify 
names-files with the 
"*" operator. 


CL_$NO_STAR_NAMES 
Does not allow user to 
specify names-files. Treats the 
"*" just like any other character. 


CL _ $KEYWORD _DELIM 
Prevents CL_$GET_ARG 
and CL_$GET_NAME 
from returning an "unused" 
flag as an argument. The 
calls return FALSE if they 
find a flag. 


CL _ $NO _ KEYWORD __ DELIM 
Causes no special treatment 
of unread flags by 
CL_$GET_ARG and 
CL_$GET_NAME. The procedures 
return the flags as if they 
were arguments. 


CL_$DASH_NOP 
The CL treats the hyphen "-" as a 
name. Normally, the hyphen is an 
identifier for the standard 
input stream. 


CL_$DASH__NAMES 
The CL reads names from 
standard input when it finds 
a hyphen.* 


CL_$DASH_DFT_NOP 
Suppresses any special action when 
there are no arguments on the 
command line. 


CL_$NAME_DFT_STDIN 
Causes the CL to read names 
from standard input if no arguments 
appear on the command line.* 


CL _ $NO _ COMMENTS 
Causes no special treatment 
of characters enclosed 
in brackets. 


CL_$COMMENTS 
Causes CL to ignore all 
characters enclosed in brackets 
when reading a names-file. Do not 
use in commands that accept derived 
names; you must use brackets to 
specify tag expressions. 



* Made available to remain compatible with previous software releases. 
Obsolete for new software development. 

program _ name 

Name of program, in UNIV character string format. CL uses this name when reporting any 
errors. 

program _len 

Length of "program _ name." This is a 2-byte integer. 

USAGE 

Use this call to initialize the CL when you want to provide the arguments to parse, rather 
than having the CL read arguments from the command line. You provide the CL with the 
arguments to parse by making subsequent calls to CL parse routines, 
CL_$PARSE_ARGS, CL_ SPARSE _INPUT, or CL_$PARSE_LINE. You could use 
CL_$INIT to initialize the CL and then call a parsing routine, but this is a cleaner and 
faster method. 
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CL_ $SET _DERIVED _ COUNT 

CL_$SET_DERIVED_COUNT 

Tells the CL how many derived names follow each wildcard-name or pathname on the 
command line. 



FORMAT 

CL_$SET_DERIVED_COUNT (count) 

INPUT PARAMETERS 

count 

Number of derived names that you expect to follow a wildcard-name or pathname. This is a 
2-byte integer. 

USAGE 

Use this call when you expect derived names. Usually, you specify a "count" of one; but 
potentially, you can have several derived names from one source name. 

This call is optional, but recommended. 
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CL $SET NAME PREFIX 



Defines a character string that the CL adds to the beginning of each name read from the 
token list. 



FORMAT 

CL_$SET_NAME_PREFIX (prefix. prefix_len) 

INPUT PARAMETERS 

prefix 

Prefix to insert in front of the name read from the token list. This is a UNIV character 
string. 

prefix _len 

Number of characters in "prefix." This is a 2-byte integer. 

USAGE 

Use this call to add text before a name read by CL_$GET_NAME. For example, use this 
call to add "/sys/print M before a file to be queued. The CL adds this prefix to the 
beginning of each argument read by CL_$GET_NAME before it resolves wildcards. 
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CL_$SET_ OPTIONS 

Adds specified options to the set of CL options defined in the CL_$INIT or CL_$SETUP 
call. 



v 



FORMAT 

CL_$SET_OPTIONS ( [cl_option] ) 

INPUT PARAMETERS 

cl_option 

Set of options, in CL_$OPT_SET_T format, that tells the CL how to read the command 
line. This is a 4-byte integer. These options control how the CL interacts with the user. 

You must specify all the options you want, except the default options. 

The chart below lists the default CL options and their mutually-exclusive alternatives. 



Default Option 


Mutually-Exclusive Alternatives 


CL_$WILDCARDS 

Causes CL_$GET_NAME to resolve 

wildcards and return the resolved 

names. 


CL _ $NO _ WILDCARDS 
Causes CL _ $GET _ NAME to return 
wildcard-names verbatim; it does 
not resolve them. 


CL__$NO__MATCH_WARNING 
Displays a warning message On 
error output when a wildcard 
does not match existing 
pathnames. 


CL_$NO_MATCH_OK 
Displays no warning or error 
message when a wildcard does not 
match existing pathnames. 

CL_$NO_MATCH_ERROR 
Displays an error message on 
error output, and terminates 
the program when a wildcard 
does not match an existing 
pathname. 


CL _ $VERIFY_ NONE 
CL_$GET_NAME does not 
verify any names with the 
user. 


CL_$VERIFY WILD 
CL_$GET_NAME verifies 
only names resolved by 
wildcards with the user. 

CL_$VERIFY_ALL 
CL_$GET_NAME verifies all 
names with the user. 
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Default Option 


Mutually- Exclusive Alternatives 


CL_$STAR_NAMES 
Allows user to specify 
names-files with the 
"*" operator. 


CL_$NO_STAR_NAMES 
Does not allow user to 
specify names-files. Treats the 
■ * " just like any other character. 


CL $KEYWORD DELIM 
Prevents CL $GET_ARG 
and CL_$GET_NAME 
from returning an "unused" 
flag as an argument. The 
calls return FALSE if they 
find a flag. 


CL _ $NO ^KEYWORD _DELIM 
Causes no special treatment 
of unread flags by 
CL_$GET_ARG and 
CL_$GET_NAME. The procedures 
return the flags as if they 
were arguments. 


CL_$DASH_NOP 
The CL treats the hyphen "-" as a 
name. Normally, the hyphen is an 
identifier for the standard 
input stream. 


CL_$DASH_NAMES 
The CL reads names from 
standard input when it finds 
a hyphen.* 


CL _ $DASH _ DFT _ NOP 
Suppresses any special action when 
there are no arguments on the 
command line. 


CL_$NAME_DFT_STDIN 
Causes the CL to read names 
from standard input if no arguments 
appear on the command line.* 


CL _ $NO _ COMMENTS 
Causes no special treatment 
of characters enclosed 
in brackets. 


CL_$COMMENTS 
Causes CL to ignore all 
characters enclosed in brackets 
when reading a names-file. Do not 
use this in commands that accept 
derived names because you must 
use brackets to specify the 
tag expressions you want to 
use in a derived name. 



* Made available to remain compatible with previous software releases 
Obsolete for new software development. 



USAGE 



Use this call to add options to the set of CL options that you defined when you initialized 
the CL with a call to CL_$INIT or CL_$SETUP. If you want to remove any options 
from the set, use CL_$RESET_ OPTIONS. 



Apollo Confidential 



CL-39 



CL 



CL_$SET_ STREAMS 

CL_$SET_STREAMS 

Tells the CL to use the specified names as the default input and output channels. 

FORMAT 

CL_$SET_STREAMS ( stream_in. error_in. stream_out. err_out) 

INPUT PARAMETERS 

stream _ in 

Name of stream used for standard input, in STREAM__$ID_T format. The default value 
is stream __$stdin (0). 

error __ in 

Name of stream used for error input, in STREAM_$ID_T format. The default value is 
stream _$errin (2). 

stream _ out 

Name of stream used for standard output, in STREAM_$ID_T format. The default 
value is stream _$stdout (1). 

error _ out 

Name of stream used for error output, in STREAM_$ED__T format. The default value is 
stream _$errout (3). 

USAGE 

Use this call to redirect the default input and output channels to the specified streams. This 
allows the user to specify another file for input or output. 



V 
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CL_$SET_VERB 

CL_$SET_VERB 

Defines a verb that the CL displays before each query message. 

FORMAT 

CL_$VERB(verb, verb_len) 

INPUT PARAMETERS 

verb 

Text that the CL prints before each pathname in user query messages. This is a UNTV 
character string. 

verb _ len 

Number of characters in "verb." This is a 2-byte integer. 

USAGE 

Use this call to add text before a pathname read by CL_$GET_NAME when you are 
expecting the CL to query users. When the CL queries users, it will write the verb, the 
pathname, and then a question mark. 

The CL verifies all pathnames when you specify the CL_$VERIFY_ALL CL option, or 
when you use the CL_$VERIFY system call. It verifies wildcard matches if you specify 
CL $VERIFY WILD. 
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CL_$SET_WILD_OPTIONS 

CL _ $SET _ WILD _ OPTIONS 

Defines the wildcard options that tell the wildcard manager how to expand wildcards. 

FORMAT 

CL_$SET_WILD_OPTIONS ( [wild_option] ) 

INPUT PARAMETERS 

wild __ option 

Set of options, in CL_$WILD_SET_T format, that tells the CL wildcard manager how 
to expand wildcard options. This is a 2-byte integer. 

If you want to change the default set of wildcard options that the CL established at 
initialization, you must specify the all the options you want to set. 

The CL wildcard options are: 

CL_$WILD_FILES 

Matches names of files (default). 

CL_$WILD_DIRS 

Matches names of directories (default). 

CL_$WILD_LINKS 

Matches names of links (default). 

CL_$WILD_EXCLUSIVE (' 

Matches the highest directory of a given wildcard. This is useful for V. 

commands that operate on entire directories, such as COPY__TREE, or 
WRITE _BACKUP. Since they operates on all subdirectories, there's no 
need to match further. 

CL_$WILD_CHASE_LINKS 

Chases links that point to directories or files. 

CL_$WILD_FIRST 

Stops at the first match of a given wildcard; otherwise, subsequent calls 
to CL_$GET_NAME expand all names that match the wildcard. 

USAGE 

Use this call to change the default set of CL wildcard options. 
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CL_$VERIFY 

CL_$VERIFY 

Prompts the user for a yes/no response. This call adds a question mark after the specified 
prompt. 

FORMAT 

answer := CL_$VERIFY (name , name_len) 

RETURN VALUE 

answer 

Returns the user's repsonse to the yes/no query in CL_$ANSWER_T format. This is a 
2-byte integer. 

The user's response can be either of the following values: 
CL_$YES Include this pathname on the token list. 

CL_$NO Ignore this pathname. 

CL_$QUIT Stop prompting user to verify pathnames. 

CL_$GO Include all the pathnames that you find on the token list without further 

query. 

INPUT PARAMETERS 

name 

Name with which the user is prompted. This is a UNIV character string. 

name_len 

Number of characters in "name." This is a 2-byte integer. 

USAGE 

Use this call to prompt the user for a yes/no response. It writes the name followed by a 
question mark. You can call CL_$SET_VERB before this call to include a text string 
with the prompt. 
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ERRORS 

CL_$ARG_TOO_LONG 

User supplied an argument that is longer than allowed. You specify the maximum 
length required at the time of the call. 

CL_$DUPLICATE_SET_ELEMENT 

User supplied a duplicate character, detected by the CL_$GET_SET call. 

CL_$INVAL1D_DECIMAL_NUMBER 

User supplied an invalid decimal number to be converted by the CL__$GET__NUM 
call. 

CL_$INVALID_SET_ELEMENT 

User supplied an invalid character, detected by the CL_$GET_SET call. 

CL _ $MISSING _REQ _DERIVED _NAME 

User did not supply the required derived name after a keyword for the 
CL_$GET_FLAGGED_DERIVED_NAME call. 

CL_$NO_MATCH_FOR_WILDCARD 

There are no pathnames in the user's working directory that match the wildcard 
specified. 

CL_$NOT_ENOUGH_ARGUMENTS 

User did not supply enough arguments, detected by the CL_$CHECK_FLAG call. 

CL _ $TOO _MANY_ ARGUMENTS 

User supplied more arguments than the program can handle, detected by the 
CL_$CHECK_FLAG call. 

CL _ $UNPARSED _KEYWORD 

User supplied a keyword that cannot be handled by program, detected by the 
CL $CHECK UNCLAIMED call. 
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FU DATA TYPES 



CONSTANTS 



NAME $PNAMLEN MAX 



256 



Maximum length of a pathname. 



DATA TYPES 



NAME SPNAME T 



FU tCONTEXT T 



An array of up to NAME _$PNAMLEN_ MAX 
(256) characters. 

A 2-byte integer. Location of error returned by 
some FU calls. One of the following pre-defined 
values: 



FU $OPT T 



FU_$SRC 

Error occurred in the source object or tree. 

FU_$DST 

Error occurred in the target object or tree. 

FU_$UNK 

Unknown whether the error occurred , in the 

source or target object or tree. 

A 2-byte integer. FU options passed to many FU 
calls. One of the following pre-defined values: 

FU_$LIST_FILES 
List files operated on. 

FU_$LIST_DIRS 

List directories operated on. 

FU_$LIST_LINKS 
List links operated on. 

FU_$REPLACE 

Replace target with a copy of the source. 

FU_$MERGE 

Merge source and target if both are 

directories. For files and links with the same 

name in source and target, it deletes the 

target and replaces it with a copy of the 

source. 

FU_$COE 

Continue to the next object if an error occurs 

while processing an object. 

FU_$PRINT_ERRORS 

Print errors on the error output stream. 
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FU_$LIST_DEL 

List objects deleted as a result of a replace 

operation. Obsolete; use 

FU_$LIST_D_DIRS, 

FU_$LIST_D_FILES, 

FU_$LIST_D_LINKS instead. 

FU_$HELP 

Display detailed usage information. It has no 
meaning under AEGIS, used for a Boot Shell 
utility only. 

FU_$QUIT 

Has no meaning under AEGIS, used for a 

Boot Shell utility only. 

FU_$BEF_TIME 

For copy tree, copy only those objects whose 
dtm (date/time last modified) is before the 
given date and time. 

FU_$AFT_TIME 

For copy tree, copy only those objects whose 

dtm (date/time last modified) is after the 



given date and time 



FU_$FORCE_DEL 

Force deletion of a target during a replace 

operation if user has owner M P M rights. 

FU_$FORCE 

Force a copy in FU_$MOVE if the source 

and target files are not located on the same 

volume. 

FU_$DACL 

Assign default ACL to target files. Target gets 

the default ACL of the parent (destination) 

directory. 

FU_$SACL 

Assign ACL of source object to target object. 

Target gets the same ACL as the source 

object. 

FU_$RENAME 

Change the name of existing object with the 
target pathname before creating copy. If 
target name is in use and cannot be deleted 
during a replace operation, it appends today's 
date to the target pathname. 

FU_$LIST_D_FILES 
List deleted files. 
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FU_$LIST_D_DIRS 
List deleted directories. 

FU_$LIST_D_LINKS 
List deleted links. 

FU_$MERGE_DST 

Merge source and target if both are 

directories. For Hies and links with the same 

name in source and target, the target remains 

unchanged. 

FU_$USE_PRESERVE 
Reserved. 

FU_$SUBS 

Retain the source ACL for objects which 

belong to protected subsystems. 

FU_ $PRESERVE_DT 

Preserve the source dtm (date/time last 

modified) and dtu (date/time last used). 

FU_$SPARSE 
Reserved. 



FU $OPT SET T 



STATUS $T 



FU_$DEL_WHEN_UNLKD 

Delete object when it becomes unlocked. 

A 2-byte integer. A set of FU options in 
FU_$OPT_T format. For a list of options, see 
FU_$OPT_T above. 

A status code. The diagram below illustrates the 
STATUS _$T data type: 



Total byte: 

Size: 4 offset 31 



0: 

1: 
2: 



\L 



integer 



or 



24 
16 



integer 



field name 
all 

fail 
subsys 

mode 
code 
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Field Description: 

ALL 

All 32 bits in the status code. 



TIME $CLOCKH T 



FAIL 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

SUBSYS 

The subsystem that encountered the error (bits 

24 - 30). 

MODC 

The module that encountered the error (bits 16 - 

23). 

CODE 

A signed number that identifies the type of error 
that occurred (bits - 15). 

Internal representation of time. The high 32 bits of 
the TME_$CLOCK_T data type. The diagram 
below illustrates the TIME_$CLOCKH_T data 
type: 



Total 
Size: 6 


byte: 
offset 








field name 


Predefined 
Record: 




31 


15 


time_$clockh_t 


0: 

4: 


integer 


high 








integer 


low 




Field ] 


Description: 










HIGH 

High 32 bits of the clock. 








LC 
Lo 


w 16 bits of t 


he clock. 
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FU_$CMP_TREE 

FU_$CMP_TREE 

Compare a source tree to a target tree. 

FORMAT 

FU_$CMP_TREE(source_patnname. sour ce_name_len . targe t_p at hname . targe t_name_len. 
fu_options. error_pathname . error_pathname_len. status) 

INPUT PARAMETERS 

source _pathname 

Pathname of the source file to be compared, in NAME_$PNAME_T format. This is an 
array of up to 256 characters. 

The source file must be the same type of object as the target. 

source _ name _ len 

Number of characters in " source _ pathname." This is a 2-byte integer. 

target _ pathname 

Pathname of the target file to be compared,in NAME_$PNAME_T format. This is an 
array of up to 256 characters. 

The target file must be the same type of object as the source. 

target _ name _ len 

Number of characters in " target _ pathname." This is a 2-byte integer. 

fu_ options 

FU compare options in FU_$OPT_SET_T format. This is a 2-byte integer. Specify any 
combination of the following predefined values: 

FU_$COE Continues to the next file, if an error occurs while processing a file. 

FU_$LIST_DIRS 

Lists directories as they are compared. 

FU_$LIST_FILES 

Lists files as they are compared. 

FU_$LIST_LINKS 

Lists links as they are compared. 

FU_$PRINT_ERRORS 

Displays errors to the error output stream. 



/" ~\ 
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FU SCMP TREE 



INPUT/OUTPUT PARAMETERS 

error _ pathname 

Pathname of the file where an error occurred, if any, in NAME_$PNAME_T format. 
This is an array of up to 256 characters. 

This is valid only if "status" does not equal zero. 

error __ pathname _ len 

Length of " error _ pathname." This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the FU 
Data Types section for more information. 

USAGE 

Use this call to compare all the objects of a source tree against all objects in a target tree. 
This call reports any objects catalogued in the source that do not also appear in the target. 
However, it does not compare the target to the source, so it does not list objects that appear 
in the target that do not appear in the source. 

FU_$CMP__TREE compares objects byte-by-byte. If it encounters a difference, it reports 
the difference, stops comparing that file and goes on to compare the next objects in the tree. 
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FU_$COPY_FILE 

FU_$COPY_FILE 

Copies a file from the source pathname to the target pathname. 

FORMAT 

FU_$COPY_FILE(source_pathname. source_name_len. target_patnname, 
targe t_name_len. fu_options. error_context, status) 

INPUT PARAMETERS 

sour ce _ pathname 

Pathname of the source file to be copied, in NAME__$PNAME_T format. This is an 
array of up to 256 characters. 

If the source name is a link name, it resolves the link, and copies the file to which the link 
refers. 

source _ name _ len 

Number of characters in " source _ pathname. " This is a 2-byte integer. 

target _ pathname 

Pathname of the target file, in NAME_$PNAME_T format. This is an array of up to 
256 characters. 

If pathname is a directory, it copies the source to the target directory. You cannot specify a 
link as a target name. 

target _ name _ len 

Number of characters in "target _ pathname." This is a 2-byte integer. 

fu_ options 

FU copy options in FU_$OPT_SET_T format. This is a 2-byte integer. Specify any 
combination of the following predefined values: 

FU__$COE Continues to the next file, if an error occurs while processing a file. 

FU_$DACL Assigns the target file's ACL. The target file gets the default ACL of the 
parent (destination) directory. Invalid if FU_$SACL is set. 

FU_$DEL_WHEN_UNLKD 

Deletes object when it becomes unlocked as a result of a replace 
operation. (That is, if the user set the FU_$REPLACE option.) 

FU_$FORCE_DEL 

Forces deletion of a target during a replace operation if user has protect 
("P") rights. (That is, if the user set the FU_$REPLACE option.) 

FU_$LIST_D_FELES 

Lists files deleted as a result of a replace operation. (That is, if the user 
set the FU_$REPLACE option.) 

FU_$LIST_FILES 

Lists files copied. 
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FU_$COPY_FILE 

FU_$PRESERVE_DT 

C Preserves the source file's dtm (date/time last modified) and dtu 

) (date/time last used) if the user set the FU_$REPLACE option and the 

file was copied. 

FU_$PRINT_ERRORS 

Displays errors to the error output stream. 

FU_$RENAME Changes the name of existing object with the target pathname before 
making a copy. If target name is in use and cannot be deleted during a 
replace operation, it appends today's date to the target pathname. 

FU_$REPLACE Replaces the target with a copy of the source. 

FU_$SACL Assigns the target file's ACL. The target file gets the same ACL as the 

source file. Invalid if FU__$DACL is set. 

FU_$SUBS Retains the source ACL for objects which belong to protected subsystems. 

OUTPUT PARAMETERS 

error _ context 

Indicates where an error occurred, in FU_$CONTEXT_T format. This is a 2-byte 
integer. On error, the call can return any one of the following predefined values: 

FU_$SRC Error occurred in the source object. 

FU_$DST Error occurred in the target object. 

FU_$UNK Error undefined. 

This is valid only if "status" does not equal zero. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the FU 
Data Types for more information. 

USAGE 

Use this call to copy a source file to a target file. This call copies only files; use 
FU_$COPY_TREE to copy directories and their subordinate objects. 
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FU_$COPY_TREE 

FU_$COPY_TREE 

Copies, merges, and replaces files, directories, and links. 

FORMAT 

FU_$COPY_TREE(source_pathname, source_name_len. target_pathname. 

target_name_len. fu_options, before_time. after_time. 
error_pathname . error_pathname_len. status) 

INPUT PARAMETERS 

source _ pathname 

Pathname of the source file, link, or directory tree to be copied, in NAME_$PNAME_T 
format. This is an array of up to 256 characters. 

source _ name __ len 

Number of characters in " source _ pathname." This is a 2-byte integer. 

target _ pathname 

Pathname of the target file to be created, replaced, or merged, in NAME_$PNAME_T 
format. This is an array of up to 256 characters. 

The target pathname can be derived from the source pathname. It cannot be a link, logical 
volume entry directory, or network root directory. 

target _ name _ len 

Number of characters in " target _ pathname." This is a 2-byte integer. 

fu_ options 

FU options, in FU_$OPT_SET_T format. This is a 2-byte integer. Specify any 
combination of the following predefined values: 

FU_$AF_ TIME Copies only those objects whose dtm (date/time last modified) is after the 
given date and time, in TIME_$CLOCKH_T format. 

FU_$BF_ TIME Copies only those objects whose dtm (date/time last modified) is before 
the given date and time, in TIME_$CLOCKH_T format. 

FU__$COE Continues to the next file, if an error occurs while processing a file. 

FU__$DACL Assigns the target directory's ACL. Each directory has its own ACL plus 

two default ACLs, one for its files and another for its subdirectories. Each 
subdirectory and file gets the target directory's default ACLs. 

FU_$DEL_WHEN_UNLKD 

Deletes the object when it becomes unlocked as a result of a replace 
operation. (That is, if the user set the FU_$REPLACE option.) 

FU_$FORCE_DEL 

Forces deletion of a target during a replace operation if user has protect 
("P") rights. (That is, if the user set the FU_$REPLACE option.) 

FU_$LIST_D_FILES 

Lists files deleted as a result of a replace operation. 
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FU_$COPY_TREE 

FU_$LIST_D_DIRS 

Lists directories deleted as a result of a replace operation. 

FU_$LIST_D_LINKS 

Lists links deleted as a result of a replace operation. 

FU_$LIST_DIRS 

Lists directories as they a.-e copied. 

FU_$LIST_FBLES 

Lists files as they are copied. 

FU_$LIST_LINKS 

Lists links as they are copied. 

FU_$MERGE Merges the source and target if both are directories. If the target exists, 
it merges the source into the target, replacing files and links, and 
combining directories. If the target does not exist, FU_$COPY_TREE 
duplicates the source as the target. 

If both source and target are directories, FU_$COPY_TREE compares 
their contents, object by object. Objects that exist in the source but not 
in the target are created in the target. Objects that exist in the target 
but not in the source remain unchanged. 

If files and links have the same name in the source and target, 
FU_$COPY_TREE deletes the target and replaces it with a copy of the 
source. If directories have the same name in both source and target, it 
merges them. 

If the source and target are not both directories, FU_$COPY_TREE 
deletes the target and replaces it with the source. 

FU_$MERGE_DST 

Merges source and target if both are directories. It works the same as 
FU_$MERGE except that files and links with the same name in both 
the source and target remain unchanged in the target. 

FU_$PRESERVE_DT 

Preserves the source file's dtm (date/time last modified) and dtu 
(date/time last used) if the user set the FU_$REPLACE option and the 
file was copied. 

FU_$PRINT_ERRORS 

Displays errors to the error output stream. 

FU_$RENAME Changes the name of existing object with the target pathname before 
making a copy. If target name is in use and cannot be deleted during a 
replace operation, it appends today's date to the target pathname. 

FU_$REPLACE Replaces the target with the source. It deletes the tree starting at the 
target pathname and copies the entire source tree in its place. If the 
target pathname does not exist, it creates one and duplicates the source. 
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FU_$SACL Assigns the target directory's ACL. Each subdirectory and file gets the 

same ACL as the source directory. 

FU_$SUBS Retains the source ACL for objects which belong to protected subsystems. 

before_time 

Specified time, in TIME_$CLOCKH_T format. This data type is 4 bytes long. 

Copies only those files whose dtm (date/time last modified) is before the given date and 
time. 

afer_time 

Specified time, in TIME_$CLOCKH_T format. This data type is 4 bytes long. 

Copies only those files whose dtm (date/time last modified) is after the given date and time. 

OUTPUT PARAMETERS 

error _ pathname 

Returns the pathname of the file where an error occurred, in NAME_$PNAME_T format. 
This is an array of up to 256 characters. 

This is valid only if "status" does not equal zero. 

error _ pathname _ len 

Length of " error _ pathname." This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the FU 
Data Types section for more information. 

USAGE 

Use this call to copy directories, subordinate objects, and links to a target directory. This is 
most useful in calls where you want to copy any pathname, and do not care whether the 
pathname is a file or tree. 

If you want to copy files only, use FU_$COPY_FILE. 



v 
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FU_$DELETE_FILE 

Deletes a specified file. 

FORMAT 

FU_$DELETE_FILE (pathname. pathname_len. force. delete__when_unlocked, status) 

INPUT PARAMETERS 

pathname 

Pathname of the source file to be deleted, in NAME_$PNAME__T format. This is an 
array of up to 256 characters. 

pathname _ len 

Number of characters in "pathname. - This is a 2-byte integer. 

force 

If TRUE, forces file deletion if user has owner rights, even if user does not have delete 
rights. This is a Boolean value. 

delete _ when _ unlocked 

If TRUE, it deletes delete the file when it becomes unlocked. This is a Boolean value. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the FU 
Data Types section for more information. 

USAGE 

Use this call to delete a file. It is similar to NAME _$DELETE_ FILE except that it 
allows you to delete locked objects. 
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FU_ $DELETE_ TREE 

Deletes a directory and all its descendants. 

FORMAT 

FU_$DELETE_TREE (pathname. pathname_len, fu__options. 

error_pathname . error_pathname_len. status) 

INPUT PARAMETERS 

pathname 

Pathname of the directory to be deleted, in NAME__$PNAME_T format. This is an 
array of up to 256 characters. 

If "pathname" is a directory, it deletes the directory and all subordinate objects 
(subdirectories, links, and files). If "pathname" is a link, it deletes the link, but has no 
effect on the files and directories named by the link. 

p athname _ len 

Number of characters in "pathname." This is a 2-byte integer. 

fu_ options 

FU delete options in FU_$OPT_SET_T format. This is a 2-byte integer. Specify any 
combination of the following predefined values: 

FU__$COE Continues to the next file, if an error occurs while processing a file. 

FU_$DEL_WHEN__UNLKD 

Deletes object when it becomes unlocked. 

FU_$FORCE_DEL 

Forces deletion if user has protect ("P") rights. 

FU_$LIST_D_FILES 

Lists files deleted. 

FU_$LIST_D_DIRS 

Lists directories deleted. 

FU_$LIST_D_LEMKS 

Lists links deleted. 

FU_$LIST_DIRS 

Lists directories as they are copied. 

FU_$LIST_DIRS 

Lists directories as they are deleted. 

FU_$LIST_FILES 

Lists files as they are deleted. 

FU_$LIST_LINKS 

Lists links as they are deleted. 
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FU_$PRINT_ERRORS 

Displays errors to the error output stream. 

OUTPUT PARAMETERS 

error _ pathname 

Returns the pathname of the file where an error occurred, in NAME_$PNAME_T format. 
This is an array of up to 256 characters. 

This is valid only if "status" does not equal zero. 

error __ pathname _ len 

Length of " error __ pathname." This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the FU 
Data Types section for more information. 

USAGE 

Use this call to delete a directory, and all the files, links and subdirectories within it. This 
call is most useful when you want to delete a pathname, and you do not care if the 
pathname is a file or directory. 
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FU_$INIT 

Initializes the file and tree utility (FU). You must use this call before any other FU calls. 

FORMAT 

FU_$INIT 

USAGE 

Use this call to initialize the FU. This call allocates read/write storage space for subsequent 
FU calls. You can release the storage with FU_$RELEASE_ STORAGE before 
terminating your program. 
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FU_$MOVE_FELE 

Moves a file to a different location in the naming tree. 

FORMAT 

FU_$MOVE_FILE(source__pathname. source_name_len. target_pathname, 
targe t_name_l en. fu_options. error_context. status) 

INPUT PARAMETERS 

source _ pathname 

Pathname of the source file to be moved, in NAME_$PNAME_T format. This is an 
array of up to 256 characters. 

source _ name _ len 

Number of characters in " source _ pathname. " This is a 2-byte integer. 

target _ pathname 

Pathname of the new file location, in NAME_$PNAME_T format. This is an array of up 
to 256 characters. 

target _ name _ len 

Number of characters in " target _ pathname." This is a 2-byte integer. 

fu_ options 

FU options in FU_$OPT_SET_T format. This is a 2-byte integer. Specify any 
combination of the following predefined values: 

FU_$COE Continues to the next file, if an error occurs while processing a file. 

FU_$DACL Assigns the target file's ACL. The target file gets the default ACL of its 

parent (destination) directory. Invalid if FU_$SACL is set. 

FU_$DEL_WHEN_UNLKD 

Deletes the object when it becomes unlocked as a result of a replace 
operation. (That is, if user set the FU_$REPLACE option.). 

FU_$FORCE Forces a copy of the target if the source and target are not located on the 
same volume. 

FU_$LIST_D_FILES 

Lists files deleted as a result of a replace operation. 

FU_$LIST_D_DIRS 

Lists directories deleted as a result of a replace operation. 

FU_$LIST__D_LINKS 

Lists links deleted as a result of a replace operation. 

FU_$LIST_DIRS 

Lists directories moved. 

FU_$LIST_FILES 

Lists files moved. 

Apollo Confidential FU-17 FU 



FU_$MOVE_FILE 

FU_$LIST_LINKS 

Lists links moved. 

FU_$PRESERVE_DT 

Preserves the source file's dtm (date/time last modified) and dtu 
(date/time last used) if the user set the FU_$REPLACE option and the 
file was copied. 

FU_$PRINT_ERRORS 

Displays errors to the error output stream. 

FU_$RENAME Changes the name of existing object with the target pathname before 
making a copy. If the target object is in use and cannot be deleted 
during a replace operation, it appends today's date to the target 
pathname. 

FU_$REPLACE Replaces the target with a copy of the source. 

FU_$SACL Assigns the target file's ACL. The target file gets the same ACL as the 

source file. Invalid if FU_$DACL is set. 

FU_$SUBS Retains the source ACL for objects that belong to protected subsystems. 

OUTPUT PARAMETERS 

error _ context 

Indicates where an error occurred, in FU_$CONTEXT_T format. This is a 2-byte 
integer. On error, the call can return any one of the following predefined values: 

FU__$SRC Error occurred in the source object. 

FU_$DST Error occurred in the target object. 

FU_$UNK Error undefined. 

This is valid only if "status" does not equal zero. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the FU 
Data Types section for more information. 

USAGE 

Use this call to move a specified file to another location in the naming tree. You can also 
use FU_$MOVE__FILE to move a directory name, if the directory is located on the same 
volume. 



FU FU-18 Apollo Confidential 



FU $RELEASE STORAGE 



FU_$RELEASE_STORAGE 

Releases read/write storage used by FU calls. 

FORMAT 

FU_$RELEASE_STORAGE 

USAGE 

Use this call to release the read/write storage used by FU calls. FU allocates storage during 
copy operations, so you would usually use this call after your program performs numerous 
copy operations. 

You can use this call any time after you initialize the FU with a FU_$INIT system call. 
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FU_$RENAME_UNIQUE 

FU_ $RENAME_UNIQUE 

Renames a pathname to create a unique name by appending today's date to the pathname. 

FORMAT 

FU_$RENAMEJJNIQUE (pathname. pathname_len. fu_options. status) 

INPUT PARAMETERS 

pathname 

Pathname to be changed, in NAME_$PNAME_T format. This is an array of up to 256 
characters. 

pathname _ len 

Number of characters in "pathname." This is a 2-byte integer. 

fu_ options 

FU options in FU_$OPT_SET_T format. This is a 2-byte integer. Specify any 
combination of the following predefined values: 

FU_$COE Continues to the next file, if an error occurs while processing a file. 

FU_$LIST_DIRS 

Lists directories operated on. 

FU_$LIST_FILES 

Lists files operated on. 

FU_$LIST_LINKS 

Lists links operated on. 

FU_$PRINT_ERRORS 

Displays errors to the error output stream. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS__$T format. This data type is 4 bytes long. See the FU 
Data Types section for more information. 

USAGE 

Use this call to rename a file so it will have a unique pathname. The call appends a period 
and today's date and time to the specified pathname. 
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FU_$SET_PROG_NAME 

FU_$SET_PROG_NAME 

Identifies the program name when the FU manager reports any errors. 

FORMAT 

FU_$SET_PROG_NAME (pathname, pathname_len) 

INPUT PARAMETERS 

pathname 

Name of program, in NAME__$PNAME_T format. This is an array of up to 256 
characters. 

pathname _ len 

Number of characters in "pathname." This is a 2-byte integer. 

USAGE 

Use this call to identify your program. The FU manager returns this program name when 
reporting any errors that occur. 
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ERRORS 

FU_$CANT_PROCESS 

Cannot delete or copy system directory. 

FU_$COMPARE_FAILED 

Compare failed, detected by FU_$CMP_TREE. 

FU__$DEST_IN_SOURCE 

Target file of FU_$COPY_TREE contained in source. 

FU_$DIFF_VOLS 

Cannot move objects across volumes, detected by FU_$MOVE_FILE. 

FU_$NOT_LEAF 

File is a directory, detected by FU_$COPY_FILE. 

FU_$SAME_OBJECT 

Cannot copy source over itself. 

FU _ $UNREC _ NSTYPE 

Naming server entry type is unknown. 

FU_$UNREC_SYSTYPE 

Type of system object is unknown, detected by FU _$ CMP _ TREE. 



V. 
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loader DATA TYPES 
CONSTANTS 

LOADER_TABLE_SIZE 2048 Maximum number of sections allowed in an array of 

the data type, PM_$SECT_INFO. 

NAME_$PNAMLEN_MAX 256 Maximum length of a pathname. 

DATATYPES 

NAME_$PNAME_T An array of up to NAME__$PNAMLEN_MAX 

(256) characters. 

PM_$0PTS A 2-byte integer. Set of options that define how an 

object module gets loaded with PM_$LOAD. One 
of the following pre-defined values: 

PM_$COPY_PROC 

Causes PM_$LOAD to copy the object 
module into read/write storage so that you 
can write to the object module without 
changing the original. 

PM_$INSTALL 

Tells PM_$LOAD that it is loading a library 

containing global variables, not a program. / 

PM_$LOAD makes all the global entry 

points that were marked at binding available 

to other programs. 

PM_ $NO _UNRESOLVEDS 

Causes PM_$LOAD to report an error if 

there are any unresolved global variables. 

PM_$LOAD_GLOBALS 
Reserved. 

PM_*INSTALL_SECTIONS 
Tells PM_$LOAD that it's loading a library 
containing global sections. PM_$LOAD 
makes these global sections, which were 
marked at binding, available to all programs. 

PM_ $LOAD _ WRITABLE 

Causes PM_$LOAD to load the object 
module with read/write access. Normally, the 
object module has read/only access. Specify 
this option when you want to write to the 
object module without copying it first. 

PM_$LOADER_OPTS A 4-byte integer. A set of LOADER options in 

PM_$OPTS format. For a list of options, see 
PM $0PTS above. 
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LOADER DATA TYPES 



PM $SECT INFO 



A record of information within the 
PM_$LOAD_INFO data type. The diagram 
below illustrates the PM_$SECT_INFO data 
type: 



Total 
Size: 40 



Predefined 
Record: 

PM_$SECT_INFO 



byte: 
offset 



0: 



31 



32: 

36: 



15 



char 



integer 



integer 



field name 



name 



* * 



loc 
ien 



NAME 

The name of the section, a character array of up 

to 32 elements. 

LOC 

A 4-byte integer. Location of section 

information. 



PM $LOAD INFO 



LEN 

A 4-byte integer. Length of section. 

An argument returned by PM_$LOAD. The 
diagram below illustrates the PM_$LOAD_INFO 
data type: 



Total t 
Size: 81926 c 


jyte: 
ffset 

0: 
4: 
6: 


31 


15 





field name 


Predefined 
Record: 

PM_$LOADJNFO 


integer 




start_addr 




integer 


n_sects 


Predefined 




* 


* 


sects: 


Record: 

PM $SECT INFO 






char 


name 
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loc 




integer 


Ien 
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81886: ( 6 + (2048 x 40) -40 ) 
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LOADER 



loader DATA TYPES 



PM $LOAD INFO PTR T 



STATUS ST 



Field Description: 

START_ADDRESS 

A UNIV__PTR indicating the start address of 
the object module; i.e., the first instruction to 
execute. If the object is a library, the first 
instruction is the initialization point; if the 
object is a program, it is the main entry point. 

N_SECTS 

Number of sections contained in object module. 



SECTS 

Location of sections. An array 

PM_$SECT_INFO records, up 
LOADER_TABLE_SIZE (2048 bytes). 



of 
to 



A 4-byte integer. The address of a returned 
PM_$LOAD_INFO record. 

A status code. The diagram below illustrates the 
STATUS _$T data type: 



Total byte: 

Size: 4 offset 31 



0: 



1: 
2: 



n31 



integer 



or 



24 
16 



integer 



field name 
all 

fail 
subsys 

mode 
code 



Field Description: 

ALL 

All 32 bits in the status code. 

FAIL 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

SUBSYS 

The subsystem that encountered the error (bits 

24 - 30). 



LOADER 
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LOADER DATA TYPES 



MODC 

The module that encountered the error (bits 16 - 

23). 



UNIV PTR 



CODE 

A signed number that identifies the type of error 

that occurred (bits - 15). 

A 4-byte integer. A pointer to allocated storage. 
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LOADER 



PM_$CALL 

PM_$CALL s~ 

\ 
Invokes a program at the start address returned by PM_$LOAD. V 

FORMAT 

long_int := PM_$CALL( start_address ) 

RETURN VALUE 

long_int 

Returns a 32-bit integer. This value has no meaning unless you expect a return value from 
the invoked program. For details, see the chapter on process manager system calls in Part I 
of this manual. 

INPUT PARAMETERS 

start _ address 

Starting address of the object module. This is a UNIV_PTR, which is the first field of the 
PM_$LOAD_INFO record, returned by PM_$LOAD. 

USAGE 

This call invokes a program at the current program level, at the start address returned by 
PM_$LOAD. The start address is the first field of the PM_$LOAD_INFO data type. 
For example, if you declare "sec^nfo" of the type PM_$LOAD_INFO, you would ^" 

invoke the object module with the following statement: 

pm_junk := pm_$call( sec_info.start_addr ); 

Before using this call, You must load the program with the PM_$LOAD system call. 
Using these two system calls is similar to using PGM_$INVOKE, except that 
PGM_$INVOKE creates a new program level and performs cleanup handling. 
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PM_$LOAD 

PM_$LOAD 

Loads a specified object module or library at the current program level. 

FORMAT 

PM_$LOAD (program, program_len. loader_options. num_sects. load_info, status ) 

INPUT PARAMETERS 

program 

Name of the object to load, in NAME_$PNAME_T format. This is an array of up to 256 
characters. 

program _len 

Number of characters in "name." This is a 2-byte integer. 

loader _ options 

Loader options in PM_$LOADER_OPTS format. This is a 2-byte integer. Specify any 
combination of the following predefined values: 

PM_$COPY_PROC 

Causes PM_$LOAD to copy the object module procedure text to avoid 
changing the original object module. If you do not specify this option, 
PM_$LOAD maps the object module directly. 

PM_$INSTALL Indicates that PM_$LOAD is loading a library containing global 
variables, not a program. The entries are marked at binding. 

PM_ $INSTALL_ SECTIONS 

Causes PM_$LOAD to define global sections so that you can share 
information among programs. 

PM_$LOAD_WRITABLE 

Causes PM_$LOAD to load the object module as writable, allowing you 
read/write access. Normally, the object module has read/only access. 

PM _ $NO _ UNRESOLVEDS 

Causes PM_$LOAD to report an error if there are any unresolved global 
variables. 

num_ sects 

Number of sections. This is a 2-byte integer. If "num_sects" is greater than zero, it is the 
maximum number of sections that you want information on, which is returned in 
" load __ info." If "num_ sects" is zero, PM_$LOAD returns only the start address of the 
object module. 

OUTPUT PARAMETERS 

load _ info 

Returns the start address of the object module in PM__$LOAD_INFO format. If 
"num_ sects" does not equal zero, it also returns the name and location of each section in 
the object module. For more information on this data type, see the LOADER Data Types 
section. 



Apollo Confidential LOADER-7 LOADER 



PM $LOAD 



status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the 
LOADER Data Types section for more information. 

USAGE 

Loads a library or program object module at the current program level. It converts the 
object module on the disk to executable form and returns the starting address of the 
module. You must invoke the program with the PM_$CALL system call. 

Using these two system calls is similar to using PGM__$INVOKE, except that 
PGM__$INVOKE creates a new program level and performs cleanup handling. 
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LOADER ERRORS 



ERRORS 

KG_$NO_SPACE 

Not enough storage space for global entry points exported by this module for a 
read/write section. 

LOADER_$BKPTS_IN_OBJ 

Leftover breakpoints exist in object module. This occurs when you set breakpoints in 
the original object module by using PM__$WRITABLE rather than making a copy 
with PM_$COPY_PROC. The breakpoints remain in the object module if it 
terminates abnorally. 

LOADER_$DNx60_REQUIRED 

Attempted to execute an object that contains instructions specifically for the Dnx60 
series on a non Dnx60 machine. 

LOADER _ $M020 _ REQUIRED 

Attempted to execute an object that contains instructions specifically for the M020 
series on a non M020 machine. 

L0ADER_$M881_REQU1RED . 

Attempted to execute an object that contains instructions specifically for the M881 
series on a non M881 machine. 

LOADER _ $NO _ COPY _ SPACE 

Not enough read/write storage space to copy the object module, detected because the 
PM_$COPY_PROC option was set. 

LOADER_$NO_PROC_SPACE 

Not enough address space to map the object module. 

LOADER_ $NO _ RW _ SPACE 

Not enough read/write storage space to load the object module. 

LOADER_$NOT_A_PROGRAM 

The name you supplied is not an object module. 

LOADER_$PEB_REQUIRED 

Attempted to execute an object that contains instructions specifically for the floating 
point performance enhancement board (PEB), on a machine that does not have the 
board. 

LOADER _ $TOO _MANY _ SECTIONS 

Too many sections in object module. 

LOADER_$TOO_MANY_UNDEFINED 

Too many undefined references in object module. 

LOADER _ $UNDEF _ GLBL 

Made reference to an unresolved global at runtime. 

LOADER_$UNDEF_GLBL_IN_LIB 

Library contains unresolved global variables, detected because the 
PM_$NO_UNRESOLVEDS option was set. 
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LOADER_$UNK_INIT_REQUIRED 

C library initialization required; no C library is installed. /LEB/CLIB must always be 
present to run a C program. In practice, you should never see this error, since you 
cannot boot a node without installing CLIB. 

LOADER _ $WRONG _ VERSION 

The LOADER could not understand the object module format because the version 
differed. 
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login DATA TYPES 



CONSTANTS 



NAME SPNAMLEN MAX 



256 Maximum length of a pathname. 



DATA TYPES 



NAME_$PNAME_T 

LOGIN_$STRING_T 
LOGIN SOPT T 



An array of up to NAME_$PNAMLEN_MAX 
(256) characters. 

An array of up to 256 characters. 

A 2-byte integer. Options for LOGIN _$LOGIN 
system call. One of the following pre-defined 
values: 



LOGIN_$LOCAL_CONN 
Reserved. 



LOGIN SOPT SET T 



LOGIN $PROC REC T 



LOGIN_$LOG_EVENTS 

Indicates that you are supplying a procedure 

to record user's attempts to log in. 

A 4-byte integer. A set of LOGIN options in 
LOGIN _$OPT_T format. For a list of options, 
see LOGIN_$OPT_T above. 

A record of pointers to LOGIN functions and 
procedures that you supply to LOGIN_$LOGIN. 
The diagram below illustrates the 

LOGIN _$PROC_ REC _T data type: 



Total 
Size: 16 
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4: 
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integer 


pread 


Predefined 


integer 


pwrite 


Record: 
LOGIN_$PROC_RECT 


integer 


help 


integer 


openjog 






Field Description: 
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STREAM_$E>_T 
STATUS $T 



LOGIN DATA TYPES 

PREAD 

Pointer to read function that you supply to 

LOGEM_$LOGIN. 

PWRITE 

Pointer to write procedure that you supply to 

LOGIN_$LOGIN. 

HELP 

Pointer to help procedure that you supply to 

LOGIN_$LOGIN. 

OPEN_L0G 

Pointer to open log function that you supply to 
LOGIN_$LOGIN. 

A 2-byte integer. Open stream identifier. 

A status code. The diagram below illustrates the 
STATUS _$T data type: 



Total 
Size: 4 



byte: 
offset 31 



0: 

0: 

1: 
2: 



n31 



integer 



or 



24 
16 



integer 



field name 
all 

fail 
subsys 

mode 
code 



Field Description: 

ALL 

All 32 bits in the status code. 

FAIL 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

SUBSYS 

The subsystem that encountered the error (bits 

24 - 30). 
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LOGIN 



LOGIN DATA TYPES 

MODC 

The module that encountered the error (bits 16 - 

23). 

CODE 

A signed number that identifies the type of error 
that occurred (bits - 15). 

UNIV_ptr A 4-byte integer. A pointer to allocated storage. 
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LOGIN_$CHHDIR 

LOGIN_$CHHDIR 

Changes the home directory that is listed in the registry ACCOUNT file. 

FORMAT 

LOGIN_$CHHDIR (login_ptr. home_dir. home_dir_len. status ) 

INPUT PARAMETERS 

login _ptr 

Pointer to internal LOGIN datatypes in LOGIN_$PTR format. This is a UNTV_PTR 
data type, and is 4 bytes long. 

home_dir 

Name of the supplied home directory. This is a UNIV character string. 

home _ dir _ len 

Number of characters in ,, home_di^. ,, This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the 
LOGIN Data Types section for more information. 

USAGE 

Use this call to change a user's home directory listed in the network registry account file. 
Before using this call, you must use LOGIN_$OPEN to initialize the LOGIN manager, and 
LOGIN_$SET_PPO to set the PPO (person, project, organization) files to the user whose 
home directory you want to change. Use LOGIN_$LOGIN when you are finished changing 
registry ACCOUNT files. 
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LOGIN_$CHPASS 

LOGIN _$CHPASS 

Change the password that is listed in the registry account file. 

FORMAT 

LOGIN_$CHPASS (login_ptr. password. pass_len. status ) 

INPUT PARAMETERS 

login _ptr 

Pointer to internal LOGIN datatypes in LOGIN_$PTR format. This is a UNTV_PTR 
data type, and is 4 bytes long. 

password 

Name of the supplied password. This is a UNIV character string. 

pass__len 

Number of characters in "password. * This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the 
LOGIN Data Types section for more information. 

USAGE 

Use this call to change the user's password in the registry account file. Before using this 
call, you must use LOGIN__$OPEN to initialize the LOGIN manager, and 
LOGIN _$SET_PPO to set the PPO (person, project, organization) files to the user whose 
password you want to change. Use LOGIN _$LOGIN when you are finished changing 
registry ACCOUNT files. 
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LOGIN_$CKPASS 

LOGIN _$CKPASS 

Checks the supplied password against the one listed in the registry ACCOUNT file. 

FORMAT 

LOGIN__$CKPASS (login_pti\ password. pass_len. status ) 

INPUT PARAMETERS 

login _ptr 

Pointer to internal LOGIN datatypes, in LOGIN_$PTR format. This is a UNIV_PTR 
data type, and is 4 bytes long. 

password 

Name of the supplied password. This is a UNIV character string. 

pass_len 

Number of characters in "password. " This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. This data type is 4 bytes long. See the 
LOGIN Data Types section for more information. 

USAGE 

Use this call to check the supplied password against the password listed in the registry 
ACCOUNT file. Before using this call, you must use LOGIN_$OPEN to initialize the 
LOGIN manager, and LOGIN _$SET_PPO to set the PPO (PERSON, PRJECT, 
ORGANIZATION) files to the user whose password you want to check. Use 
LOGIN_$LOGIN when you are finished changing registry ACCOUNT files. 
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LOGIN _$CLOSE 

LOGIN_$CLOSE 

Closes a LOGIN operation. 

FORMAT 

LOGIN_$CLOSE (login_ptr. status ) 

INPUT PARAMETERS 

login _ptr 

Pointer to internal LOGIN datatypes in LOGIN_$PTR format. This is a UNIV_PTR 
data type, and is 4 bytes long. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the 
LOGIN Data Types section for more information. 

USAGE 

Use this call to release the resources that the LOGIN manager used for LOGIN operations. 
The LOGIN manager updates the account files at this time. If a previous LOGIN call had 
difficulty with an account file, a LOGIN_$CLOSE can fail, which means that the registry 
will not be updated accurately. You will have to repeat the entire sequence since you 
opened LOGIN with LOGIN _$LOGIN. Call this routine even if the LOGIN _$OPEN 
fails. 



V, 
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LOGDM_$ERR_CONTEXT 

LOGIN_$ERR_CONTEXT 

Locates the file that failed during LOGIN operation. 

FORMAT 

LOGIN_$ERR_CONTEXT (login_ptr, err_status. bad_name. name_len, status ) 

INPUT PARAMETERS 

login _ptr 

Pointer to internal LOGIN datatypes, in LOGIN_$PTR format. This is a UNTV_PTR 
data type, and is 4 bytes long. 

OUTPUT PARAMETERS 

err _ status 

Error status, in STATUS _$T format. This data type is 4 bytes long. See the LOGIN Data 
Types section for more information. 

bad _ name 

Pathname of the file that failed, in NAME_$PNAME_T format. This is an array of up 
to 256 characters. 

name_len 

Number of characters in " bad _ name." This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the 
LOGIN Data Types section for more information. 

USAGE 

Use this call to locate the pathname of the PPO file failed during a LOGIN operation. 
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LOGIN_$LOGIN 

LOGIN_$LOGIN 

Allows a user to log in to a program. 

FORMAT 

ok := L0GIN_$L0GIN (stream. login_opt. login_procedures. status) 

RETURN VALUE 

ok 

Returns TRUE if LOGIN _$LOGIN is successful, returns FALSE if not. 

INPUT PARAMETERS 

stream 

Number of the stream where the user will log in, in STREAM_$ID_T format. This is a 
2-byte integer. 

login __ opt 

Option you can specify in your log in procedure, in LOGIN_$OPT_SET_T format. This 
is a 2-byte integer. Specify the predefined value: 

LOGIN_$LOG_EVENTS 

Tells LOGIN_$LOGIN that you are supplying a procedure to record log 
in events. 

login procedures 

Pointers to input/output routines that you supply to LOGIN _$LOGIN, in 
LOGIN_$PROC_REC_T format. 

The following are the procedures and functions you supply to LOGIN_$LOGIN with their 
input and output parameters. 

NOTE: The INPUT parameters are the parameters that LOGIN_$LOGIN supplies 
to the routines . The OUTPUT parameters are the parameters that the 
routines pass to L0GIN_$L0GIN . 

YOUR__READ Reads input line and passes it to LOGIN _$LOGIN. 
Format 

int := YOUR_READ(stream, inbuf, inlen, pstr, plen, echo, fillbuf, fillbuflen) 

Return Value 

int Returns an integer indicating the length of the message in "inbuf." 

Input Parameters 

stream Number of stream associated with input, in STREAM_$ID__T format. 

This is usually STREAM _$STDIN. 
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LOGIN $LOGIN 



inlen Maximum length of "inbuf." This is a 2-byte integer. 

pstr Prompt string in LOGIN _$STRING_T format. This is a UNIV 

character array of 256 characters. 

plen Length of "pstr." This is a 2-byte integer. 

echo Indicates whether the input should be echoed. LOGIN__$LOGIN returns 

TRUE when prompting for a PPO, FALSE when prompting for -a 
password. 

fillbuf Pre-fill buffer with string in LOGIN __$STRING_T format. This is a 

UNIV character array of 256 characters. Do not use this parameter, as it 
is specific to the Display Manager. 

fillbuflen Length of "fillbuf. " This is a 2-byte integer. Do not use this parameter, 

as it is specific to the Display Manager. 

Output Parameters 
inbuf 

Login string that YOUR _ READ passes to LOGIN _$LOGIN, in 
LOGIN _$STRING_T format. This is a UNTV character array of 256 
characters. 

YOUR _ WRITE Writes error and help messages to output. 
Format 

YOUR _ WRITE (stream, pstr, plen) 

Input Parameters 

stream Number of stream associated with output, in STREAM _$ID_T format. 

This is usually STREAM _$STDOUT. 

pstr Message to output, in LOGIN _$STRING_T format. This is a UNIV 

character array of 256 characters. 

plen Length of "pstr." This is a 2-byte integer. 

YOUR __ HELP Provides help message that LOGIN _$LOGIN supplies when user types 
h[elp] at the prompt. 

Format 
YOUR_HELP (stream) 

Input Parameters 

stream Number of stream on which to output help procedure, in 

STREAM $ID T format. 
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LOGIN_$LOGIN 

YOUR__OPEN_LOG 

Records log in events in a log file. 

Format 

ok := YOUR_OPEN_LOG (Iog_file, log _ file _len, log_stream) 

Return Value 

ok Returns TRUE if YOUR_OPEN_LOG opened successfully, returns 

FALSE if not. 

Input Parameters 

log_file Name of your log file, in LOGIN _$STRING_T format. This is a 

UNIV character array of 256 characters. 

log__file_len Length of "log_file.** This is a 2-byte integer. 

Output Parameters 

log _ stream 

Number of the stream associated with " log _ file," in STREAM _$ID_T 
format. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. This data type is 4 bytes long. See the 
LOGIN Data Types section for more information. 

USAGE 

Use this call to write a log-in procedure that allows you to limit user's access to a specified 
program. LOGIN_$LOGIN does not handle input/output directly. Rather, you supply 
your own input/output routines so you can handle the special input/output needs of your 
application. The arguments of these routines must correspond to the parameters listed 
above. 

To supply LOGIN _$LOGIN with the addresses of your input/output procedures, you must 
compile them in a separate module. 

When the user supplies a PPO and password to LOGIN_$LOGIN, the system call checks 
the supplied password against the password listed in the registry. If the passwords match, 
LOGIN _$LOGIN will log the user in. 

This system call corresponds to the Shell LOGIN command. 
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LOGIN_$OPEN 

LOGIN_$OPEN 

Initializes the LOGIN manager. 

FORMAT 

LOGIN_$OPEN (mode. login_ptr. status ) 

INPUT PARAMETERS 

mode 

Mode of LOGIN operation, in LOGIN_$MODE_T format. This is a 2-byte integer. 
Specify one of the following predefined values: 

LOGIN_$READ Initializes LOGIN in read access mode only. Allows user to view registry 
account files only. 

LOGIN _$UPDATE 

Initializes LOGIN in read/write access mode. Allows user to view and 
change registry account files. 

OUTPUT PARAMETERS 

login _ptr 

Pointer to internal LOGIN datatypes in LOGIN_$PTR format. This is a UNTV_PTR 
data type, and is 4 bytes long. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the 
LOGIN Data Types section for more information. 

USAGE 

LOGIN _$OPEN sets up storage for internal LOGIN datatypes. Use this call before using 
the following LOGIN system calls: 

• LOGIN _$CHKPASS 

• LOGIN _$CHPASS 

• LOGIN_$CHHDIR 

Even if LOGIN_$OPEN fails, you must also call LOGIN_$CLOSE. 
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LOGIN_$SET_PPO 

LOGIN_$SET_PPO 

Sets the PPO (person, project, organization) files of the user whose account file you want to 
check or change. 

FORMAT 

LOGIN_$SET_PPO (login_ptr, ppo. ppo_len. status ) 

INPUT PARAMETERS 

login _ptr 

Pointer to internal LOGIN datatypes, in LOGIN_$PTR format. This is a UNIV_PTR 
data type, and is 4 bytes long. 

ppo 

Name of user's PPO file. This is a UNTV character string. 

ppo_len 

Number of characters in "ppo." This is a 2-byte integer. If "ppo_len M is zero, 
LOGIN_$SET_PPO uses the PPO files of the user who is currently logged in. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the 
LOGIN Data Types section for more information. 

USAGE 

Use this call to set the PPO files before checking or making any changes to the registry. If 
you do not call this routine explicitly, the LOGIN manager automatically sets the PPO files 
to the user who is currently logged in. 
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LOGIN ERRORS 



ERRORS 

LOGIN _ $BAD _ PASSWD 

User supplied an invalid password, detected by LOGIN __$CKPASS. 

LOGIN_$ERR_EXIT 

User wants the call to exit. 

LOGIN__$ERR_SHUT 

User wants the caller to shut down. 

LOGIN_$NO_ROOM 

Not enough storage to initialize LOGIN'S internal datatypes. 
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PM 



PM DATA TYPES 



CONSTANTS 



NAME $COMPLEN MAX 



32 



Maximum length of a name. 



DATA TYPES 



NAME SNAME T 



UID $T 



An array of up to NAME_$COMPLEN_MAX 
(32) characters. 

A process UID. The diagram below illustrates the 
UID_$T datatype: 
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Predefined 
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UID $T 



byte: 
offset 
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integer 



integer 



field name 

high 
low 



STATUS $T 



Field Description: 

HIGH 

The high four bytes of the UID. 

LOW 

The low four bytes of the UID. 

A status code. The diagram below illustrates the 
STATUS _$T data type: 
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Field Description: 

ALL 

All 32 bits in the status code. 

FAIL 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

SUBSYS 

The subsystem that encountered the error (bits 

24 - 30). 

MODC 

The module that encountered the error (bits 16 - 

23). 

CODE 

A signed number that identifies the type of error 
that occurred (bits - 15). 
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PM_$GET_HOME_TXT 

PM_$GET_HOME_TXT 

Returns the home directory of the calling process as a string. 

FORMAT 

PM_$GET_HOME_TXT (maxlen. home, len) 

INPUT PARAMETERS 

maxlen 

Maximum number of characters to be returned (at most, the size of the buffer you assign 
for home). This is a 2-byte positive integer. This parameter need not exceed 256. 

OUTPUT PARAMETERS 

home 

Pathname of the home directory for the SID (log-in identifier) of this process. This is an 
array of up to 256 characters. 

len 

Number of characters returned in the home parameter. This is a 2-byte positive integer. 

USAGE 

The home directory is obtained from the network registry when you log in and is inherited 
by all your processes. 
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PM_$GET_SE)_TXT 

PM_$GET_SID_TXT 

Returns the SID (log-in identifier) of the calling process as a string. 

FORMAT 

PM_$GET_SID_TXT (maxlen, sid, len) 

INPUT PARAMETERS 

maxlen 

Maximum number of characters to be returned (at most, the size of the buffer you assign 
for home). This is a 2-byte positive integer. This parameter need not exceed 140. 

OUTPUT PARAMETERS 

sid 

String containing the person, project, organization and node ID of the SID (log-in identifier) 
of this process, in the form: 

person . group . proj ect . nodeid 
This is an array of up to 140 characters. 

len 

Number of characters returned in the log-in identifier. This is a 2-byte positive integer. 

USAGE 

Your SID is the full identifier obtained from the network registry when you log in and is 
inherited by all your processes. 
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PM_$SET_NAME 

PM_$SET_NAME 

Assigns a name to a given process UID. 

FORMAT 

PM_$SET_NAME( name, length. process_uid. status) 

INPUT PARAMETERS 

name 

The name you want to give to the process in NAME_$NAME_T format. This is an array 
of up to 32 characters. 

length 

Number of characters in "name." This is a 2-byte integer. 

process _uid 

The UID of the process that you want to name in UID_$T format. This data type is 8 
bytes long. See the PM Data Types section for more information. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PM 
Data Types for more information. 

USAGE 

Use this call to assign a name to a given process. Once a process has a name, you cannot 
rename or remove the name from the process. 
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PM ERRORS 



ERRORS 

PM_$ALREADY_NAMED 

Attempted to assign a name to a process UID that was already named. You cannot 
change the name of a process already named by the Shell CRP command, or the DM 
commands, CP, CPO, or CPS. 

PM_$NOT_FOUND 

The process manager cannot find the process specified in the call. 
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PR0C2 DATA TYPES 



DATA TYPES 




PR0C2_$INF0_T 




Total 
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Process information record. The diagram below 
illustrates the PROC2_$INFO_T data type: 
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STACK_BASE 

Base address of user stack. 

STATE 

Process state - ready, waiting, etc. 

USR 

User status register. 

UPC 

User program counter. 

USP 

User stack pointer. 

USB 

User stack base pointer (A6). 
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PR0C2 DATA TYPES 



PR0C2 $UID LIST T 



PR0C2 $STATE T 



UID $T 



CPU_TOTAL 

Cumulative cpu time used by process. 

PRIORITY 
Process priority. 

An array of UIDs (in UID_ $T format) of up to 24 
elements. 

A 2-byte integer. State of a user process. Any 
combination of the following pre-defined values: 

PROC2_$WAITING 
Process is waiting. 

PR0C2_$SUSPENDED 
Process is suspended. 

PR0C2_$SUSP_PENDING 
Process suspension is pending. 

PROC2_$BOUND 
Process is bound. 

A type UID. The diagram below illustrates the 
UID_$T data type: 
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Field Description: 





HIGH 

The high four bytes of the UID. 



STATUS $T 



LOW 

The low four bytes of the UID. 

A status code. The diagram below illustrates the 
STATUS __$T data type: 
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PR0C2 DATA TYPES 
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Field Description: 

ALL 

All 32 bits in the status code. 

FAIL 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

SUBSYS 

The subsystem that encountered the error (bits 

24 - 30). 

MODC 

The module that encountered the error (bits 16 - 

23). 

CODE 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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PR0C2_$GET_INF0 

PROC2_$GET_INFO 

Returns information about a process. 

FORMAT 

PR0C2_$GET_INF0 (process-uid. info, info-buf -length, status) 

INPUT PARAMETERS 

process-uid 

The UID of the process for which you want information, in UID__$T format. This data 
type is 8 bytes long. See the PROC2 Data Types section for more information. 

You can get process UIDs by calling PROC2_$WHO_AM_I and PROC2_$LIST. 

If the process-uid in the call is the caller's own process, the only information returned is the 
stack UID and virtual address. If you want to find out the amount of CPU time used by 
the caller's process, use PROCl_$CPU_TIME. 

info- buf- length 

Length of the information buffer allotted for returned information, in bytes. This is 
normally 36 bytes. 

OUTPUT PARAMETERS 

info 

Information about the process, in PROC2_$INFO_T format. This data type is 36 bytes 
long. See the PROC2 Data Types section for more information. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the 
PROC2 Data Types section for more information. Possible values are: 

STATUS _$OK Completed successfully. 

PROC2 _ $IS _ CURRENT 

Specified calling process UID (success). 

PROC2_$UID_NOT_FOUND 

Specified UID is not on node. 

USAGE 

GET_$INFO returns information about a process when supplied with a process UID. The 
information returned consists of the following: 
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PR0C2 $GET INFO 



• The program state (ready, waiting, suspended, SUSP_PENDING, bound). 

• The User Status Register (USR). 

• The User Program Counter (UPC). 

• The user stack pointer (A7). 

• The stack base pointer (A6). 

• The amount of CPU time used. 

• The CPU scheduling priority. 
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PR0C2_$LIST 

PR0C2_$LIST 

Returns a list of existing level 2 (user) processes on the caller's node. 

FORMAT 

PR0C2_$LIST (uid-list, max-num-uids. number-uids) 

OUTPUT PARAMETERS 

uid-list 

The UIDs of the active level 2 processes on the system, in PROC2_$UID_LIST_T 
format. This is a 24-element array of UIDs. Each UID is a 4-byte integer in UID_$T 
format. 



INPUT PARAMETERS 

max-num-uids 

Maximum number of process UIDs to be returned. (At most, the size of the buffer you 
assign for "uid-list. " This is a 2-byte integer. 

OUTPUT PARAMETERS 

number-uids 

Number of active level 2 processes on the node, even if that number is greater than 
" max-num-uids. H This is a 2-byte integer. 

A 
USAGE 

The UIDs of all level 2 processes (user processes) on the caller's node, up to 
" max-num-uids, " are returned. 
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PR0C2_$SET_PRI0RITY 

PR0C2 _ $SET ^PRIORITY 

Sets the priority of a pocess. 

FORMAT 

PR0C2_$SET_PRI0RITY( process_uid, low, high, status) 

INPUT PARAMETERS 

process _uid 

The UID of the process that you want to change the priority level, in UID__$T format. 
This data type is 8 bytes long. See the PROC2 Data Types section for more information. 

low 

The lower boundary of the priority. This is a 2-byte integer within the range of 1 to 16. 
The default lower boundary is 3. 

high 

The higher boundary of the priority. This is a 2-byte integer within the range of 1 to 16. 
The default higher boundary is 14 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS__$T format. This data type is 4 bytes long. See the 
PROC2 Data Types section for more information. 

USAGE 

Use this call to change the priority of a program. The process priority is an integer ranging 
from 1 (low) to 16 (high). The Display Manager runs at a priority of (16,16). When the 
operating system decides which process to run next, it chooses the process that currently has 
the highest priority. 

The priority changes while a process executes. Its priority increases as the process waits for 
events, and decreases as it computes for long periods without waiting. 



PROC2 PROC2-8 Apollo Confidential 



PR0C2_$WH0_AM_I 

PROC2 _ $WHO _ AM_ I 

Returns the UID of the calling process. 

FORMAT 

PR0C2_$WH0_AM_I (my-uid) 

OUTPUT PARAMETERS 

my-uid 

The UID of the calling process, in UID_$T format. This data type is 8 bytes long. See the 
PROC2 Data Types section for more information. 

USAGE 

You can use a UID obtained through this call to find out information about your process 
from the PROC2 $GET INFO call. 



Apollo Confidential PROC2-9 PROC2 



PR0C2 ERRORS 



ERRORS 

PROC2 _ $BAD _ STACK_BASE 
Bad stack base. 

PROC2 _ $IS _ CURRENT 

Request is for current process. 

PROC2 _ $UK> _NOT_FOUND 

UK) of given process not found. 

PROC2_$UID_NOT_LEVEL_2 
Not a level 2 process. 

STATUS_$OK 

Successful completion. 
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rws DATA TYPES 
DATA TYPES 



RWS $POOL T 



STATUS $T 



A 2-byte integer. Types of pools to allocate 
read/write or heap storage. One of the following 
pre-defined values: 

RWS_$STD_POOL 

Standard pool makes storage accessible to 

calling process only. 

RWS_$STREAM_TM_POOL 
Stream pool makes storage accessible to 
calling program and to a program invoked 
with the UNDC EXEC system call. 

RWS_$GLOBAL_POOL 

Global pool makes storage accessible to all 

processes. 

A status code. The diagram below illustrates the 
STATUS _$T data type: 
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Field Description: 

ALL 

All 32 bits in the status code. 

FAIL 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

SUBSYS 

The subsystem that encountered the error (bits 

24 - 30). 
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Rws DATA TYPES 



UNIV PTR 



MODC 

The module that encountered the error (bits 16 - 

23). 

CODE 

A signed number that identifies the type of error 

that occurred (bits 0-15). 

A 4-byte integer. A pointer to allocated storage. 
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RWS_$ ALLOC 

RWS_$ ALLOC 

Allocates read/write storage for FORTRAN or Pascal programs. 

FORMAT 

RWS_$ALLOC (nbytes, pointer) 

INPUT PARAMETERS 

nbytes 

The number of bytes of storage needed. This is a 4-byte integer. 

OUTPUT PARAMETERS 

pointer 

The address of the new storage ?-ace, in UNIV_PTR format. This is a 4-byte integer. A 
returned address of zero means that RWS_$ALLOC could not allocate the desired storage. 

USAGE 

RWS_$ALLOC allocates the specified number of bytes of read/write storage to the calling 
process and returns the address of the storage area. 

This routine is useful for allocating different quantities of dynamic storage, depending on a 
run-time factor. 
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RWS_$ALLOC_HEAP 

RWS_$ALLOC_HEAP 

Allocates heap storage for programs. 

FORMAT 

pointer = RWS_$ALLOC_HEAP (nbytes) 

RETURN VALUE 

pointer 

The address of the new storage space, in UNIV_PTR format. This is a 4-byte integer. A 
returned address of zero means that RWS_$ALLOC_HEAP could not allocate the desired 
storage. 

INPUT PARAMETERS 

nbytes 

The number of bytes of storage needed. This is a 4-byte integer. 

USAGE 

RWS_$ALLOC_HEAP allocates the specified number of bytes of read /write storage to 
the calling process and returns the address of the storage area. 

This routine is useful for allocating different quantities of dynamic storage, depending on a 
run- time factor. 
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RWS _ $ALLOC _HEAP _POOL 

RWS_$ALLOC_HEAP_POOL 

Allocates heap storage in a specified pool. 

FORMAT 

pointer = RWS_$ALLOC_HEAP_POOL(alloc_pool, nbytes ) 

RETURN VALUE 

pointer 

The address of the new storage space, in UNTV^PTR format. This is a 4-byte integer. A 
returned address of zero (NIL) means that RWS _$ALLOC_HEAP_ POOL could not 
allocate the desired storage. 

INPUT PARAMETERS 

alloc _ pool 

Pool where storage will be allocated, in RWS_$POOL_T format. This is a 2-byte 
integer. Specify one of the following following predefined values: 

RWS_$GLOBAL_POOL 

Global pool makes storage accessible to all processes. 

RWS_$STD_POOL 

Standard pool makes storage accessible to calling program only. 

RWS_$STREAM_TM_POOL 

Stream pool makes storage accessible to calling program and to a 
program invoked with a UNIX EXEC system call. 

nbytes 

Number of bytes of storage needed. This is a 4-byte integer. 

USAGE 

RWS _$ALLOC_ HEAP _ POOL allocates a specified number of bytes of heap storage to 
the calling process and returns the address of the storage area. 

Use this call when you want to control storage access. You can specify that the storage be 
accessed by the calling process only, by the calling program and a program invoked with a 
UNIX EXEC system call, or by all programs. 

Due to a current limitation, you cannot use this call in FORTRAN programs due to 
FORTRAN calling conventions. This will be corrected in the next AEGIS Software Release. 
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RWS_$ALLOC_RW 

RWS_$ALLOC_RW 

) Allocates read/write storage for Pascal programs. 

FORMAT 

pointer = RWS_$ALLOC_RW (nbytes) 

RETURN VALUE 

pointer 

The address of the new storage space, in UNIV__PTR format This is a 4-byte integer. A 
returned address of zero means that RWS_$ALLOC__RW could not allocate the desired 
storage. 

INPUT PARAMETERS 

nbytes 

The number of bytes of storage needed. This is a 4-byte integer. 

USAGE 

RWS_$ALLOC_RW allocates the specified number of bytes of read/write storage to the 
calling process and returns the address of the storage area. 

This routine is useful for allocating different quantities of dynamic storage, depending on a 
run-time factor. 
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RWS_$ALLOC_RW_POOL 

RWS_$ALLOC_RW_POOL 

Allocates read/write storage in a specified pool. 

FORMAT 

pointer = RWS_$AlXOC_RWJPOOL(alloc_pool. nbytes ) 

RETURN VALUE 

pointer 

The address of the new storage space, in UNTV_PTR format. This is a 4-byte integer. A 
returned address of zero (NIL) means that RWS_$ALLOC_RW_POOL could not 
allocate the desired storage. 

INPUT PARAMETERS 

alloc _ pool 

Pool where storage will be allocated, in RWS_$POOL_T format. This is a 2-byte 
integer. Specify one of the following following predefined values: 

RWS_$GLOBAL_POOL 

Global pool makes storage accessible to all processes. 

RWS_$STD_POOL 

Standard pool makes storage accessible to calling program only. 

RWS_$STREAM_TM_POOL 

Stream pool makes storage accessible to calling program and to a 
program invoked with a UNIX EXEC system call. 

nbytes 

Number of bytes of storage needed. This is a 4-byte integer. 

USAGE 

RWS_$ALLOC__RW_POOL allocates a specified number of bytes of read/write storage 
to the calling process and returns the address of the storage area. 

Use this call when you want to control storage access. You can specify that the storage be 
accessed by the calling process only, by the calling program and a program invoked with a 
UNIX EXEC system call, or by all programs. 

Due to a current limitation, you cannot use this call in FORTRAN programs due to 
FORTRAN calling conventions. This will be corrected in the next AEGIS Software Release. 
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RWS _ $RELEASE_HEAP 

RWS _ $RELEASE_HEAP 

Releases storage allocated using the RWS__$ALLOC_HEAP call. 

FORMAT 

RWS_$RELEASE_HEAP 

INPUT PARAMETERS 

pointer 

The address heap storage space, in UNIV_PTR format. This is a 4-byte integer. 

This must be a pointer returned by a call to RWS_$ALLOC_HEAP. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the RWS 
Data Types section for more information. 

USAGE 

RWS _$RELEASE_ HEAP is used in conjunction with the RWS _$ALLOC_ HEAP call. 
RWS _$ALLOC_ HEAP dynamically allocates storage for a program, returning a pointer 
to the new storage. When you no longer need the storage, you release it by passing the 
pointer to RWS _$RELEASE_ HEAP. 
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RWS ERRORS 



ERRORS 

RWS _ $LEVEL _FAILURE 

User program wrote over the storage where the system stored the program level 
information. 

RWS_$NOT_HEAP_ENTRY 

Argument to RWS _$RELEASE_ HEAP did not refer to storage allocated with 
RWS_$ALLOC_HEAP. 

RWS_$SCRD3BLED_OVER 

User program wrote over the storage where the system stored the heap's process 
information. 

RWS _ $WRONG_LEVEL 

Attempted to release storage that was allocated by a program at a superior (lower) 
program level. This error can occur when using RWS_$STD_POOL or 
RWS $STREAM TM POOL. 
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CL_$GET_ARGS 1-3 
CL_$GET_DERIVED_NAME 1-15 
CL_$GET_ENUM_FLAG 1-11 
CL_$GET_FLAG 1-11, 2-2, 2-5, 4-5 
CL_$GET_FLAG_INFO 1-12, 1-17 
CL_$GET_NAME 1-3,1-13 
CL_$GET_NAME_INFO 1-17 
CL_$GET_NUM 1-3,1-13 
CL_$GET_SET 1-17 
CL_$INIT 1-3, 1-4 
CL_$KEYWORD_DELIM 1-6 
CL_$MATCH 1-17,2-19,3-18 
CL_$MATCH_ERROR 1-6 
CL_$NAME_DFT_STDIN 1-7 
CL_$NEXT 1-14 
CL_$NO_COMMENTS 1-7 
CL_$NO_KEYWORD_DELIM 1-6 
CL $NO MATCH OK 1-6 
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CL_$NO_MATCH_WARNING 1-6 
CL_$NO_STAR_NAMES 1-6 
CL_$NO_WILDCARDS 1-6 
CL_$PARSE_ARGS 1-5 
CL_$PARSE_INPUT 1-4, 1-10, 4-5 

program example 1- 10 
CL_$PARSE_LINE 1-4 

program example 1-0 
CL_$REREAD 1-17 
CL_$REREAD_FLAGS 1-17 
CL_$REREAD_NAMES 1-17 
CL_$RESET_OPTIONS 1-5,1-7 
CL_$SET_DERIVED_COUNT 1-5 
CL_$SET_NAME_PREFEC 1-5 
CL_$SET_OPTIONS 1-5,1-7 
CL_$SET_STREAMS 1-17 
CL_$SET_VERB 1-17 
CL_$SET_WILD_OPTIONS 1-5, 1-8 
CL_$SETUP 1-4,2-18 
CL_$STAR_ NAMES 1-6 
CL_$VERIFY 1-17 
CL_$VERIFY_ALL 1-6 
CL_$VERIFY_NONE 1-6 
CL_$VERIFy_WILD 1-6 
CL_$WILDCARDS 1-6 
Command line 

CL system calls to read 1-3 

how CL parses 1-2 

ignoring brackets 1-7 

initializing 1-3 

model for parsing, figure 1-3 

parsing 1- 1 

reading tokens from 1-1 
Command Line Handler 

See also CL system calls 
Comparing 

source tree to a target tree 2-2 
Copying 

file, example 2-8 

files and trees 2-2 
CP (create _ process) 4-6 
CPO (create_process_only) 4-6 
CPS (create _ process-server) 4-6 
CRP (create __a_ process) 4-6 



Date 

appending to a file 2-2 
Deleting 

files and trees 2-2 
Derived names 1-7 

definition 1-2 

getting, command line 1-15 

getting, program example 1-16 

handling 1-2 
DM commands 

CP (create _ process) 4-6 

CPO (create_process_only) 4-6 

CPS (create_process_seryer) 4-6 
DTM/DTU 

preserving 2-8 
Dynamic storage 

handling 5-1 

Error reporting 

unresolved global variables 4-2 
Errors 

CL 1-4 
Example 

returning 16- bit value with 
PM_$CALL 4-3 

File and Tree Utility 

See also FU system calls 
Flags 

checking for CL 1-11 

definition 1- 1 

getting arguments associated with, 
program example 1-15 

lowercase letters for defining 1-11 

specifying synonymous flags 1-11 

synonymous, example 1-12 
FORTRAN 

allocating storage 5-2 

storage limitation 5-2 
FU options 

providing Shell Command options with 

2-3 

setting, example 2-5 
FU system calls 

controlling operations by setting 
options 2-2 
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corresponding Shell commands 2-2 

insert files 2- 1 

overview 2-1 

releasing storage 2*6 

using in proper sequence 2-1 
FU_$AFT_TIME 2-3 
FU_$BEF_TIME 2-3 
FU_$CMP_TREE 2-2,2-15 
FU_$COE 2-3 
FU_$COPY_FILE 2-2,2-0 
FU_$COPY_TREE 2-2,2-11 
FU_$DACL 2-3 
FU_$DEL_WHEN_UNLKD 2-3 
FU_$DELETE_FILE 2-2,2-12 
FU_|DELETE_TREE 2-2,2-14 
FU_$FORCE 2-3 
FU_$FORCE_DEL 2-3 
FU_$HELP 2-3 
FU_$INIT 2-2,2-5,2-18 
FU_$LIST_D_DIRS 2-3 
FU_$LIST_D_FILES 2-4 
FU_$LIST_D_LINKS 2-4 
FU_$LIST_DEL 2-4 
FU_$LIST_DIRS 2-3 
FU_$LIST_FILES 2-3 
FU_$LIST_LINKS 2-3 
FU_$MERGE 2-4 
FU_$MERGE_DST 2-4 
FU_$MOVE_FILE 2-2,2-17 
FU_$PRESERVE_DT 2-4 
FU_$PRINT_ERRORS 2-4 
FU_$QUIT 2-4 
FU_$RELEASE_STORAGE 2-2 
FU_|RENAME 2-4 
FU_$RENAME_UNIQUE 2-2,2-18 
FU_$REPLACE 2-4 
FU_$SACL 2-4 
FU_$SET_PROG_NAME 2-2, 2-5, 

2-18 
FU_$SUBS 2-4 

Global sections 

loading library with 4-2 
Global variables 

reporting error on unresolved 4-2 



Handling 

dynamic storage 5-1 

files and trees with FU system calls 
2-1 

files, trees, FU example 2-6 
Heap 

combining adjacent free items 5—5 

creating with RAF 6-1 

free list 5-5 

overhead 6-2 

storage for initializing LOGIN 3-13 

I/O routines 

for LOGIN_$LOGIN 3-2 
Insert files 

BAF system calls 5-1 

CL system calls 1-1 

FU system calls 2-1 

loader (PM) system calls 4- 1 

LOGIN system calls 3-1 

PM system calls 4-1 

PROC2 system calls 4-1 

RWS system calls 5-1 
Installing 

a library with LOADER system calls 

4-1 
Invoking 

process with /com/shell 3-7 

Keywords 

definition 1- 1 

Library 

installing 4-2 

installing with LOADER system calls 
4-1 
LOADER system calls 

controlling load operation with options 
4-2 

converting object module to executable 
format 4-1 

difference between PGM_$INVOKE 
4-1 

installing a library with 4-1 
Loading 

and calling a program 4- 1 
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library containing global sections 4-2 
Loading object module 

See also LOADER system calls 
Local storage access 

limiting access within calling process 
5-3 
Logging in 

See also LOGIN system calls 
LOGIN system calls 

changing registry 3- 1 

closing file 3-13 

insert files 3-1 

overview 3-1 

proper sequence for changing account 

file 3-12 

tailoring LOGIN operation with 3-1 
See also LOGIN_$LOGIN 
LOGIN_$CHHDIR 3-1,3-13,3-16 
LOGIN_$CHPASS 3-1,3-13,3-15 
LOGIN_$CKPASS 3-1,3-13,3-15 
LOGIN_$CLOSE 3-1,3-13 
LOGIN_$ERR_CONTEXT 3-16 
LOGIN_$LOG_EVENTS 3-2, 3-3, 3-4 
LOGIN_$LOGIN 3-1,3-7 

example 3-2 

examples of 3-4 

I/O routines for 3-2 

recording all LOGIN attempts 3-3 

writing external I/O routines for 3-3 
LOGIN_$OPEN 3-1,3-15 
LOGIN_$READ 3-13 
LOGIN_$SET_PPO 3-13, 3-15 
LOGIN_$UPDATE 3-13 

MALLOC 5-2 
Managing programs 

system calls 4-1 
Moving 

files 2-2 
Multiple processes 

sharing information among processes 

5-3 

sharing storage among 5-4 

Names- file 

definition 1-1 



specifying with * 1-6 
Naming 

a process 4-6 
a process once only 4-6 
a process, example 4-6 
file, appending a date to 2-2 

Object module 

writing on copy 4- 2 

writing on original 4-2 
Options 

checking for user-specified, CL 1-11 

command line, definition 1-1 

FU 2-2 

ignoring user-specified command line 
options 1-6 

LOADER 4-2 
Overhead 

BAF heap 5-5 

RWSheap 5-2 

RWS system calls 5-4 
Overlay process 

sharing storage with 5-3 

PAD_$COOKED 3-9 
PAD_$PUT_REC 3-9 
PAD_$RAW 3-9 
Performance 

improving BAF heap 5-5 
PGM_$GET_PUID 4-8 
PGM_$INVOKE 3-7,4-8 

alternative to 4-1 
PM system calls 

insert files 4-1 

sample program 4-6 
PM_$ALREADY_NAMED 4-6 
PM_$CALL 4-5 

returning 16- bit value with 4-3 

returning a value using 4-3 
PM_$COPY_PROC 4-2 
PM_$INSTALL 4-2 
PM_$INSTALL_SECTIONS 4-2 
PM_$LOAD 4-5 
PM_$LOAD_INFO 4-3 
PM_$LOAD_WRIATABLE 4-2 
PM ILOADER OPTS 4-2 
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PM_$NO_UNRESOLVEDS 4-2 
PM_$SET_NAME 4-1, 4-6, 4-8 
Pointers 

allocating heap for managing 5-2 
Pool 

storage, controlling access with 5-2 
PPOfile 3-13 

and LOGIN system calls 3-1 

requiring special 3-2 
PPRI (process _pirority) 4-6 
PROC2 system calls 

insert files 4-1 

sample program 4-6 
PROC2_tSET_PRIORITY 4-1,4-6,4-8 
Process 

assigning a name to 4-6 

naming once 4-6 
Process priority 

Display Manager 4-6 

example 4-6 

setting a 4-6 
Process UID 4-1 
Program level 

executing program at same 4-2 
Protected subsystem 

LOGIN 3-2 
PST (proces_statu8) 4-6 
PST (process_status) Shell command 4-6 

Recording 

log-in attempts 3-3 
Registry 

changing with LOGIN calls 3-1 
Renaming 

files 2-2 
Reporting 

error, unresolved global variables 4-2 

log- in attempts 3-3 
Reporting errors 

wildcard expansion 1-6 
RWS system calls 

handling dynamic storage with 5-1 

insert files 6-1 

when to use 5-1 
RWS fALLOC 5-2 



RWS_$ALLOC_HEAP 5-2 
RWS_$ALLOC_HEAP_POOL 5-2 
RWS_*ALLOC_RW 5-2 
RWS_$ALLOC_RW_POOL 5-2 
RWS_$GLOBAL_POOL 5-3 
RWS_$RELEASE_HEAP 5-2 
RWS_$STD_POOL 6-3 
RWS_$STREAM_TM_POOL 6-3 

Sample programs 

cl _ copy _ file 1"18 

fu_handling_files_trees 2-6 

login_change_pass_dir 3-14 

login_login 3-5 

login _ procedures 3-8 

PM_LOAD 4-4 

pm_proc2_set_name_priority 4-6 
Shared storage 5-4 
Shell 

invoking 3-7 
Shell command 

PST (process _ status) 4-6 
Shell commands 

and corresponding FU system calls 
2-2 

CRP (create _a_ process) 4-6 

PPRI (process_pirority) 4-6 

PST (proces_status) 4-6 

SIGP (signal _ process) 4-6 
SIGP (signal _ process) 4-6 
Stack 

allocating storage for 5-2 
Standard input 

reading names from 1-6, 1-7 
Start address 

of loaded program 4-3 
Storage 

allocating for FORTRAN programs 

5-2 

allocating for Pascal programs 5-2 

allocating in C programs 5-2 

handling dynamic 6-1 

maintaining strick control with BAF 
5-1 

releasing 4-2 
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releasing FU 2-6 

requesting specific amount 5-1 

shared 5-4 

specifying where storage comes from 
with BAF 5-4 

summary of types of allocation 5-3 

using a pool to control access 5-2 

when to allocate heap 5-2 

when to allocate read/write 5-2 
STREAM_$CREATE 3-11 
STREAM_$GET_REC 3-9 
STREAM_$PUT_CHR 3-8 

Tailoring 

LOGIN operation 3-1 
Token 

definition 1-1 

marked used when read 1-2 

referring to used 1-2 
Token list 

definition 1-2 

figure of 1-2 
Token pointer 

definition 1-2 
Token record 

definition 1-2 

UNIX EXEC system call 5-3 
Verifying pathnames 1-6 

Wildcard- name 

definition 1-2 
Wildcards 

expanding 1-2, 1-6 

how CL expands 1-8 

returning verbatim 1-6 
Working set 

controlling size of 5-4 

desirable behavior 5-5 

using heap to control 5-2 
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